> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/documentation/zh-tw/cheng-shi-ma-fan-li-yu-qian-yi/javascript-yu-typescript.md).

# JavaScript 與 TypeScript

了解如何使用 JavaScript 與 TypeScript 呼叫 ApiSmart API，包括模型探索、文字串流、圖片生成、檔案上傳以及非同步影片任務。

使用 JavaScript 或 TypeScript，將 ApiSmart 整合到 Node.js 應用程式、後端服務、無伺服器函式與 AI 驅動的產品中。

本指南使用標準的 `fetch` API 來示範認證、模型探索、文字與圖片生成、串流回應、檔案上傳，以及非同步影片任務。

### 🚀 開始之前

請確認您已具備：

* 已安裝 Node.js
* ApiSmart 帳戶
* 有效的 API 金鑰
* 足夠的錢包餘額以供付費請求使用

以下範例使用內建的現代 Node.js `fetch`.

你不需要安裝額外的 HTTP 用戶端程式庫。

### 🔑 設定你的 API 金鑰

請勿將你的 API 金鑰直接硬編碼在應用程式原始碼中。

將它儲存在環境變數中：

```bash
export APISMART_API_KEY="your-api-key"
```

然後在 JavaScript 或 TypeScript 中存取它：

```javascript
const API_KEY = process.env.APISMART_API_KEY;

if (!API_KEY) {
  throw new Error("尚未設定 APISMART_API_KEY");
}
```

設定 ApiSmart 基礎 URL：

```javascript
const BASE_URL = "https://gw.apismart.ai/v1";
```

對於 JSON 請求，你可以重用這些標頭：

```javascript
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};
```

請妥善保管你的 API 金鑰，切勿在前端瀏覽器程式碼、公開儲存庫或客戶端 bundle 中暴露它。

### 🧩 取得可用模型

使用以下方式取得目前的模型清單：

`GET /v1/models`

```javascript
const response = await fetch(`${BASE_URL}/models`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

const result = await response.json();

for (const model of result.data ?? []) {
  console.log(model.id);
}
```

使用傳回的：

```
data[].id
```

作為您 API 請求中的 `模型` 值於支援的 API 請求中。

模型 ID 必須完全一致，包括句點（`.`）、連字號（`-`）與版本號。

關於模型類別與目前 ID，請參閱 [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md).

### 💬 聊天完成

使用：

`POST /v1/chat/completions`

範例：

```javascript
const response = await fetch(`${BASE_URL}/chat/completions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "user",
        content: "哈囉！請介紹一下你自己。",
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

const result = await response.json();

console.log(result);
```

此請求使用與 OpenAI 相容的 `messages` 格式，且已由 ApiSmart 文件說明。

關於完整請求行為，請參閱 [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md).

### 🌊 串流文字回應

設定：

```json
{
  "stream": true
}
```

以啟用串流。

```javascript
const response = await fetch(`${BASE_URL}/chat/completions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "deepseek-v4-flash",
    messages: [
      {
        role: "user",
        content: "寫一個短篇故事。",
      },
    ],
    stream: true,
  }),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

if (!response.body) {
  throw new Error("回應本文為空");
}

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();

  if (done) {
    break;
  }

  process.stdout.write(decoder.decode(value, { stream: true }));
}
```

此範例會在資料到達時讀取並列印。

ApiSmart 目前文件說明的 Chat 串流使用 `"stream": true`；API 規格未定義獨立的 JavaScript 事件解析器或詳細的區塊結構，因此應用程式應依自身需求處理回傳的串流。

關於串流行為的概覽，請參閱 [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🖼️ 生成圖片

使用：

`POST /v1/images/generations`

```javascript
const response = await fetch(`${BASE_URL}/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "doubao-seedream-5-0",
    prompt: "日出時的山村，水彩風格",
    size: "2K",
    watermark: false,
  }),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

const result = await response.json();

console.log(result);
```

圖片生成功能預設為同步。

單張圖片通常大約需要 **20–40 秒**，而高解析度、多參考或連續請求可能需要更久。

你的 HTTP 用戶端至少應允許 **90 秒** 用於圖片生成。

### ⏱️ 設定圖片請求逾時

你可以在現代 Node.js 中使用 `AbortSignal.timeout()` ：

```javascript
const response = await fetch(`${BASE_URL}/images/generations`, {
  method: "POST",
  headers,
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
    model: "doubao-seedream-5-0",
    prompt: "一座未來城市在日落時分",
    size: "2K",
  }),
});
```

此範例使用 **120 秒** 逾時，以在建議的最小值之外提供額外時間。

如果用戶端提早中斷連線，生成仍可能完成，且仍可能產生費用。

### 🔄 依據參考圖片生成

使用 `image`:

```javascript
const response = await fetch(`${BASE_URL}/images/generations`, {
  method: "POST",
  headers,
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
    model: "doubao-seedream-5-0",
    prompt: "將這張圖片轉換成水彩畫",
    image: "https://example.com/input.jpg",
    size: "2048x2048",
  }),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

console.log(await response.json());
```

在支援的情況下，也可以將多個參考圖片 URL 作為陣列提供。

關於圖片限制與支援的參數，請參閱 [**圖片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md).

### 📤 上傳本機圖片

本機圖片上傳使用：

`POST /v1/images/edits`

此端點使用 **multipart form data**，而不是 JSON 請求本文。

現代 Node.js 範例：

```javascript
import { readFile } from "node:fs/promises";

const image = await readFile("./character.png");

const form = new FormData();

form.append("model", "doubao-seedream-5-0");
form.append(
  "image",
  new Blob([image], { type: "image/png" }),
  "character.png"
);
form.append(
  "prompt",
  "將角色放入賽博龐克環境中"
);
form.append("size", "2K");
form.append("response_format", "url");

const response = await fetch(`${BASE_URL}/images/edits`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
  body: form,
  signal: AbortSignal.timeout(120_000),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

console.log(await response.json());
```

請勿手動設定：

```
Content-Type: application/json
```

於此請求中。

使用 `FormData`時，讓執行階段自動產生 multipart `Content-Type` 與 boundary。

### 🌊 串流圖片生成

支援的圖片工作流程也可以使用 SSE 串流。

設定：

```json
{
  "stream": true
}
```

範例：

```javascript
const response = await fetch(`${BASE_URL}/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "doubao-seedream-5-0",
    prompt: "建立一個極簡產品設計序列",
    size: "2K",
    sequential_image_generation: "auto",
    sequential_image_generation_options: {
      max_images: 4,
    },
    stream: true,
  }),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

if (!response.body) {
  throw new Error("回應本文為空");
}

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { value, done } = await reader.read();

  if (done) {
    break;
  }

  process.stdout.write(decoder.decode(value, { stream: true }));
}
```

關於連續生成、SSE 行為與支援的圖片參數，請參閱 [**圖片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md) 以及 [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md).

### 🎬 建立影片任務

影片生成是非同步的。

使用下列方式建立任務：

`POST /v1/video/tasks`

```javascript
const response = await fetch(`${BASE_URL}/video/tasks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "happyhorse-1.0",
    prompt:
      "一座夜晚中的微型城市，火車穿行於街道之間",
    duration: 5,
    size: "720p",
  }),
});

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

const task = await response.json();

console.log(task);
```

保存傳回的任務 ID，以便查詢生成狀態。

影片生成遵循建立任務並查詢的工作流程，而不是讓原始請求保持開啟直到生成完成。

對於解析度與時長會影響計費的模型，請明確提供那些值，而不要依賴預設值。

### 🔄 查詢影片任務

使用：

`GET /v1/video/tasks/{id}`

```javascript
const taskId = "task_xxxxxx";

const response = await fetch(
  `${BASE_URL}/video/tasks/${taskId}`,
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

const task = await response.json();

console.log(task);
```

可能的任務狀態包括：

| 狀態          | 意義    |
| ----------- | ----- |
| `queued`    | 排隊中   |
| `running`   | 生成進行中 |
| `succeeded` | 生成完成  |
| `failed`    | 生成失敗  |
| `cancelled` | 任務已取消 |
| `expired`   | 任務已過期 |

這些是目前 API 定義的影片任務狀態。

### ⏳ 持續輪詢直到影片生成完成

簡單的輪詢迴圈可以如下所示：

```javascript
const sleep = (ms) =>
  new Promise((resolve) => setTimeout(resolve, ms));

async function waitForVideo(taskId) {
  while (true) {
    const response = await fetch(
      `${BASE_URL}/video/tasks/${taskId}`,
      {
        headers: {
          Authorization: `Bearer ${API_KEY}`,
        },
      }
    );

    if (!response.ok) {
      throw new Error(`請求失敗：${response.status}`);
    }

    const task = await response.json();

    console.log("狀態：", task.status);

    if (task.status === "succeeded") {
      return task;
    }

    if (
      ["failed", "cancelled", "expired"].includes(task.status)
    ) {
      throw new Error(
        `影片任務結束，狀態為：${task.status}`
      );
    }

    await sleep(5000);
  }
}

const result = await waitForVideo("task_xxxxxx");

console.log(result);
```

此範例每 5 秒檢查一次任務。

關於 HappyHorse、Seedance、多模態輸入與完整影片參數，請參閱 [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md).

### 🕘 擷取最近生成的圖片

使用：

`GET /v1/images`

```javascript
const params = new URLSearchParams({
  page: "1",
  page_size: "20",
});

const response = await fetch(
  `${BASE_URL}/images?${params}`,
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

console.log(await response.json());
```

### 🕘 擷取最近生成的影片

使用：

`GET /v1/videos`

```javascript
const params = new URLSearchParams({
  page: "1",
  page_size: "20",
});

const response = await fetch(
  `${BASE_URL}/videos?${params}`,
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

console.log(await response.json());
```

目前可以查詢圖片與影片歷史中最近的 **7 天**.

關於歷史欄位與儲存資訊，請參閱 [**已生成媒體歷史**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md).

### 🟦 TypeScript 範例

ApiSmart 在 TypeScript 中使用相同的 HTTP API。你可以加入自己的介面，讓應用程式程式碼更容易維護。

例如：

```typescript
interface ChatMessage {
  role: "user" | "assistant" | "system";
  content: string;
}

interface ChatRequest {
  model: string;
  messages: ChatMessage[];
  stream?: boolean;
}

const payload: ChatRequest = {
  model: "deepseek-v4-flash",
  messages: [
    {
      role: "user",
      content: "以簡單的方式解釋 REST API。",
    },
  ],
};

const response = await fetch(
  `${BASE_URL}/chat/completions`,
  {
    method: "POST",
    headers,
    body: JSON.stringify(payload),
  }
);

if (!response.ok) {
  throw new Error(`請求失敗：${response.status}`);
}

const result = await response.json();

console.log(result);
```

這些 TypeScript 介面是應用程式端的範例，而不是 ApiSmart API 定義的額外欄位。

你可以依照應用程式使用的回應結構加以擴充。

### ⚠️ 處理 API 錯誤

務必檢查 `response.ok` 再處理回應：

```javascript
const response = await fetch(`${BASE_URL}/models`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});

if (!response.ok) {
  const errorBody = await response.text();

  console.error("HTTP 狀態：", response.status);
  console.error("回應：", errorBody);

  throw new Error(`ApiSmart 請求失敗`);
}
```

常見 API 回應包括：

| 狀態            | 範例程式碼                   | 意義            |
| ------------- | ----------------------- | ------------- |
| `400`         | `invalid_request_error` | 無效的請求         |
| `401`         | `invalid_api_key`       | 無效的 API 金鑰    |
| `402`         | `insufficient_quota`    | 餘額不足          |
| `403`         | `model_not_allowed`     | API 金鑰無法使用該模型 |
| `429`         | `rate_limit_error`      | 請求速率超出限制      |
| `502` / `504` | 閘道錯誤                    | 暫時性的上游或網路問題   |
| `503`         | 服務不可用                   | 供應商或相依服務不可用   |

目前的 API 錯誤定義也包含模型能力與資源特定的錯誤。

關於完整詳情，請參閱 [**HTTP 狀態碼與 API 錯誤**](https://docs.apismart.ai/documentation/zh-tw/yi-nan-pai-jie/http-zhuang-tai-ma-yu-api-cuo-wu.md).

### 🔁 重試暫時性失敗

暫時性 `5xx` 回應可以延遲後重試。

範例：

```javascript
const sleep = (ms) =>
  new Promise((resolve) => setTimeout(resolve, ms));

async function fetchWithRetry(url, options, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(url, options);

    if (response.status < 500) {
      return response;
    }

    if (attempt === maxAttempts - 1) {
      return response;
    }

    await sleep(2 ** attempt * 1000);
  }
}
```

將重試用於暫時性的服務失敗。

不要在未修正根本問題的情況下，反覆重試認證錯誤或無效請求參數。

### ✅ JavaScript 與 TypeScript 檢查清單

在部署整合前，請確認：

* 你的 API 金鑰已安全儲存
* API 呼叫是從受信任的伺服器端環境發出
* 基礎 URL 正確
* 模型 ID 已完全正確地複製
* JSON 請求使用 `Content-Type: application/json`
* Multipart 上傳允許 `FormData` 設定內容類型
* 圖片請求有足夠的處理時間
* 串流回應是逐步消耗的
* 影片任務會持續輪詢直到達到最終狀態
* 暫時性失敗使用適當的重試策略
* 你的帳戶有足夠的錢包餘額

### ➡️ 下一步

繼續以下內容：

* [**模型與模型 ID**](https://docs.apismart.ai/documentation/zh-tw/mo-xing-yu-jia-ge/mo-xing-yu-mo-xing-id.md) — 尋找有效的模型 ID
* [**Chat Completions API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/liao-tian-bu-quan-api.md) — 建置文字生成工作流程
* [**圖片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/tu-pian-sheng-cheng-api.md) — 生成與編輯影像
* [**影片生成 API**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/ying-pian-sheng-cheng-api.md) — 建立並查詢影片任務
* [**回應模式**](https://docs.apismart.ai/documentation/zh-tw/api-zhi-nan/hui-ying-mo-shi.md) — 了解標準、串流與非同步行為
* [**已生成媒體歷史**](https://docs.apismart.ai/documentation/zh-tw/api-shi-yong-liang/sheng-cheng-mei-ti-li-shi.md) — 擷取最近生成的媒體
