---
author: OOMOL
author_url: https://oomol.com/zh-tw/about/
title: 圖像與影片 API 接入指南
description: 設定 OOMOL API key，透過 SDK 或 HTTP 呼叫圖像與影片模型，並處理非同步任務、錯誤和重試。
lang: zh-TW
canonical_url: https://oomol.com/zh-tw/docs/image-video-api/
markdown_url: https://oomol.com/zh-tw/docs/image-video-api.md
---

# 圖像與影片 API 接入指南

在可信後端透過 OOMOL Fusion API 生成和編輯圖片、建立影片。各廠商保留已支援的請求參數和回應格式。支援範圍以具體模型和操作為準，不代表相容廠商的所有 API。

## 建立 API key

在 [OOMOL Console](https://console.oomol.com/api-key) 建立個人 API key，然後在後端執行環境中設定下方環境變數。將這個 OOMOL key 用作 SDK 的 apiKey 或 HTTP Bearer token，範例不需要填入廠商金鑰。不要將 key 放進瀏覽器程式碼、公開儲存庫或日誌。

```sh
export FUSION_API_TOKEN="<your-oomol-api-key>"
```

## 選擇接入位址

服務網域是 [https://fusion-api.oomol.com](https://fusion-api.oomol.com)。請使用下表中對應廠商的完整 Base URL，保留版本路徑，不要替換成 Connector 或 ProjectConnector 位址。發起付費請求前，確認所需模型已開放，並查看[價格](/zh-tw/pricing/)。

| 廠商 | Base URL |
| --- | --- |
| OpenAI Images | `https://fusion-api.oomol.com/v1/provider/openai/v1` |
| Seedream | `https://fusion-api.oomol.com/v1/provider/seedream/api/v3` |
| Seedance | `https://fusion-api.oomol.com/v1/provider/seedance/api/v3` |
| Wanx | `https://fusion-api.oomol.com/v1/provider/wanx/api/v1` |
| Kling | `https://fusion-api.oomol.com/v1/provider/kling/` |
| MiniMax | `https://fusion-api.oomol.com/v1/provider/minimax/` |

## 執行範例

只安裝所選廠商需要的套件。將對應範例儲存為 example.ts，在伺服器端 TypeScript 環境執行。下方套件版本與儲存庫本地相容測試一致，不代表支援所有 SDK 版本。設定有效憑證且入口可用時，執行範例會發起真實生成請求。

### OpenAI Images

圖片生成與編輯；不包含其他 OpenAI API。

```sh
npm install openai@7.23.0
```

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FUSION_API_TOKEN,
  baseURL: "https://fusion-api.oomol.com/v1/provider/openai/v1",
  maxRetries: 0,
  timeout: 1_080_000,
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A ceramic mug on a wooden table",
  size: "1536x864",
  quality: "medium",
});
console.log(result);
```

### Seedream

圖片生成、參考圖與部分 SSE 輸出。

```sh
npm install @volcengine/ark-runtime@1.0.11
```

```ts
import { ArkRuntimeClient } from "@volcengine/ark-runtime";

const client = new ArkRuntimeClient({
  apiKey: process.env.FUSION_API_TOKEN,
  baseURL: "https://fusion-api.oomol.com/v1/provider/seedream/api/v3",
  retryTimes: 0,
  timeout: 125_000,
});

const result = await client.generateImages({
  model: "doubao-seedream-5-0-260128",
  prompt: "A ceramic mug on a wooden table",
  size: "2K",
  response_format: "url",
});
console.log(result);
```

### Seedance

影片生成與任務查詢。

```sh
npm install @volcengine/ark-runtime@1.0.11
```

```ts
import { ArkRuntimeClient } from "@volcengine/ark-runtime";

const client = new ArkRuntimeClient({
  apiKey: process.env.FUSION_API_TOKEN,
  baseURL: "https://fusion-api.oomol.com/v1/provider/seedance/api/v3",
  retryTimes: 0,
  timeout: 125_000,
});

const task = await client.createContentGenerationTask({
  model: "doubao-seedance-2-0-260128",
  content: [{ type: "text", text: "A boat on the ocean" }],
  duration: 5,
  resolution: "720p",
});
const status = await client.getContentGenerationTask(task.id);
console.log(task.id, status);
```

### Wanx

影片生成與任務查詢。

```sh
npm install dashscope-sdk-official@1.26.0
```

```ts
import { Configuration, VideoSynthesis } from "dashscope-sdk-official";

const client = new VideoSynthesis(new Configuration({
  apiKey: process.env.FUSION_API_TOKEN,
  basePath: "https://fusion-api.oomol.com/v1/provider/wanx/api/v1",
}));

const task = await client.asyncCall({
  model: "wan3.0-video",
  prompt: "A boat on the ocean",
  resolution: "1080P",
  duration: 5,
});
const status = await client.fetch(task.output.task_id);
console.log(task.output.task_id, status);
```

### Kling

影片生成與任務查詢。

```sh
npm install ky@1.11.0
```

```ts
import ky from "ky";

const client = ky.create({
  prefixUrl: "https://fusion-api.oomol.com/v1/provider/kling/",
  headers: { Authorization: `Bearer ${process.env.FUSION_API_TOKEN}` },
  retry: 0,
  redirect: "error",
  timeout: 30_000,
});

const task = await client.post("text-to-video/kling-3.0-turbo", {
  json: {
    prompt: "A boat on the ocean",
    settings: { duration: 5, resolution: "720p", aspect_ratio: "16:9" },
  },
}).json<{ data: { id: string } }>();
const status = await client.get("tasks", {
  searchParams: { task_ids: task.data.id },
}).json();
console.log(task.data.id, status);
```

### MiniMax

影片生成與任務查詢。

```sh
npm install ky@1.11.0
```

```ts
import ky from "ky";

const client = ky.create({
  prefixUrl: "https://fusion-api.oomol.com/v1/provider/minimax/",
  headers: { Authorization: `Bearer ${process.env.FUSION_API_TOKEN}` },
  retry: 0,
  redirect: "error",
  timeout: 30_000,
});

const task = await client.post("v2/video_generation", {
  json: {
    model: "MiniMax-H3",
    content: [{ type: "text", text: "A boat on the ocean" }],
    duration: 5,
    resolution: "768P",
    ratio: "16:9",
  },
}).json<{ task_id: string }>();
const status = await client.get(
  `v2/query/video_generation/${encodeURIComponent(task.task_id)}`,
).json();
console.log(task.task_id, status);
```

## 查詢影片結果

影片範例建立任務後只查詢一次。請先儲存回傳的任務 ID。建立請求成功表示任務已受理，不代表影片已生成。使用同一 OOMOL 身分查詢同一任務，直到廠商回傳終態。查詢之間留出間隔；成功或失敗後停止查詢，並讀取對應的結果或錯誤欄位。查詢請求失敗不等於生成任務失敗，也不要為了檢查進度重新建立任務。

## 處理錯誤和重試

同時檢查 HTTP 錯誤和回傳的任務狀態。驗證、餘額檢查可能回傳閘道錯誤，格式與廠商錯誤不同。驗證失敗時檢查 OOMOL key；權限或餘額錯誤時檢查帳號及[帳單](https://console.oomol.com/billing/recharge)；參數錯誤時核對模型、操作和參數值；遇到限流時降低並行數，並遵循回應中提供的重試提示。

建立請求逾時、連線中斷或伺服器錯誤時，生成結果可能尚不確定。保留任務 ID、請求 ID 和錯誤資訊；已有任務 ID 時優先查詢。不要自動重送生成請求，否則可能建立另一個付費任務。OpenAI 和方舟範例關閉了 SDK 重試，ky 還關閉了重新導向；DashScope 沿用已驗證的 SDK 設定。業務層可以設定等待上限，但逾時後不要盲目重新提交。

## 檔案、串流輸出與結果資料

上傳、參考素材和串流輸出的限制因廠商而異。OpenAI 範例僅涵蓋 Images API，不包含聊天、Responses 或其他 OpenAI API。Seedream 支援部分 SSE 操作，這裡的 OpenAI 圖片入口為同步回傳。處理串流輸出時，收到部分事件不代表已收到完成事件。

下載回傳的媒體 URL 時使用獨立用戶端，不要攜帶 OOMOL Authorization 請求標頭，也不要假定媒體連結永久有效。用戶端中斷連線不保證取消已被上游受理的生成任務。遇到不支援的操作或結果不確定的請求，請聯絡[支援](mailto:support@oomol.com)，提供請求或任務 ID，不要傳送金鑰。

返回[圖像與影片 API 產品頁](/zh-tw/image-video-api/)。

## API 介面參考

[API 介面參考](https://fusion-api.oomol.com/public/docs?lang=zh-cn) · [OpenAPI JSON](https://fusion-api.oomol.com/public/openapi.json?lang=zh-cn)