> ## 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，該 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 物件，我們可以從緩衝區建立它
    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)

我們隨時為您提供協助！