> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript / TypeScript

[![@sunra/client npm package](https://img.shields.io/npm/v/@sunra/client?color=%237527D7\&label=JavaScript\&style=flat-square)](https://www.npmjs.com/package/@sunra/client)

### 介绍

JavaScript/TypeScript 客户端库提供了一个易于使用的接口来与 Sunra 的服务交互。

### 安装

要将客户端集成到您的项目中，请使用 npm 安装：

<CodeGroup>
  ```bash npm theme={null}
  npm install @sunra/client
  ```

  ```bash pnpm theme={null}
  pnpm add @sunra/client
  ```

  ```bash yarn theme={null}
  yarn add @sunra/client
  ```
</CodeGroup>

### 功能

#### 调用端点

Sunra 通过队列系统管理端点请求，确保可靠性和可扩展性。使用 `subscribe` 方法提交请求并等待结果。

**示例：**

```javascript theme={null}
import { sunra } from "@sunra/client";

const result = await sunra.subscribe("black-forest-labs/flux-kontext-pro/text-to-image", {
  input: {
    prompt: "一个玻璃茶壶，里面装着盛开的花茶，放在阳光透过窗户照射的木桌上，温柔的晨光。",
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      console.log(update.logs)
    }
  },
});

console.log(result.data);
console.log(result.requestId);
```

#### 队列管理

使用这些方法管理您的请求：

##### 提交请求

提交请求并检索 `request_id` 以供后续使用。

**示例：**

```javascript theme={null}
import { sunra } from "@sunra/client";

const { request_id } = await sunra.queue.submit("black-forest-labs/flux-kontext-max", {
  input: {
    prompt: "一个玻璃茶壶，里面装着盛开的花茶，放在阳光透过窗户照射的木桌上，温柔的晨光。",
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
  },
});
```

##### 检查请求状态

检索请求的状态。

**示例：**

```javascript theme={null}
import { sunra } from "@sunra/client";

const status = await sunra.queue.status({
  requestId: "pd_eTYYuw4EqYLzRBHgnAMHA8zH",
  logs: true,
});
```

##### 检索请求结果

获取已完成请求的结果。

**示例：**

```javascript theme={null}
import { sunra } from "@sunra/client";

const result = await sunra.queue.result({
  requestId: "pd_eTYYuw4EqYLzRBHgnAMHA8zH",
});

console.log(result.data);
console.log(result.requestId);
```

#### 存储

`storage` API 允许您上传文件并接收 URL，然后可以在模型端点请求中使用。这对于需要文件输入的模型特别有用，如图像转视频或语音转文本。

<Note>最大文件大小：100MB</Note>

##### 在浏览器中上传文件

您可以允许用户直接从浏览器上传文件。以下示例显示如何使用 `<input type="file">` 元素选择文件并上传。

<CodeGroup>
  ```javascript upload.js theme={null}
  import { sunra } from "@sunra/client";

  const fileInput = document.getElementById('file-input');

  fileInput.addEventListener('change', async (event) => {
    const file = event.target.files[0];
    if (file) {
      try {
        const url = await sunra.storage.upload(file);
        console.log('文件上传成功：', url);
        // 现在您可以将此URL与模型端点一起使用
      } catch (error) {
        console.error('上传失败：', error);
      }
    }
  });
  ```

  ```html index.html theme={null}
  <input type="file" id="file-input" />
  ```
</CodeGroup>

##### 在Node.js中上传文件

在 Node.js 的服务器端，您可以从本地文件系统读取文件并上传它们。

```javascript theme={null}
import { sunra } from "@sunra/client";
import { readFile } from "node:fs/promises";
import { basename } from "node:path";

async function uploadLocalFile(filePath) {
  try {
    const buffer = await readFile(filePath);
    // 客户端需要一个 File 对象，我们可以从 buffer 创建
    const file = new File([buffer], basename(filePath));

    const url = await sunra.storage.upload(file);
    console.log('文件上传成功：', url);
    return url;
  } catch (error) {
    console.error('上传失败：', error);
  }
}

uploadLocalFile("./path/to/your/image.png");
```

#### 模型端点自动上传

JavaScript SDK 可以自动为您处理文件上传。当您将 `File` 对象、`Blob` 或 base64 数据 URI 传递给模型端点的输入时，SDK 将首先将其上传到存储，然后在请求中使用生成的 URL。

这简化了流程，因为您不需要执行单独的上传步骤。

```javascript theme={null}
import { sunra } from "@sunra/client";

// 来自浏览器文件输入的 File 对象将自动上传
const fileInput = document.getElementById('file-input');
const file = fileInput.files[0];

const result = await sunra.subscribe("some-model-that-takes-images", {
  input: {
    image: file, // SDK 自动上传此文件
    prompt: "描述如何处理图像的提示"
  }
});

// base64 数据 URI 也将自动上传
const base64Image = "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...";

const result2 = await sunra.subscribe("some-model-that-takes-images", {
  input: {
    image: base64Image, // SDK 自动将其转换为 Blob 并上传
    prompt: "描述如何处理图像的提示"
  }
});
```

### 支持

加入我们的社区获得帮助或讨论：

* **Discord 社区**：[加入我们](https://discord.gg/897qCzvCcU)
* **GitHub 仓库**：[访问这里](https://github.com/sunra-ai/sunra-clients)

我们在这里为您提供帮助！