圖像與影片 API 接入指南

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

建立 API key

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

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

選擇接入位址

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

執行範例

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

OpenAI Images

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

npm install openai@7.23.0

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 輸出。

npm install @volcengine/ark-runtime@1.0.11

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

影片生成與任務查詢。

npm install @volcengine/ark-runtime@1.0.11

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

影片生成與任務查詢。

npm install dashscope-sdk-official@1.26.0

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

影片生成與任務查詢。

npm install ky@1.11.0

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

影片生成與任務查詢。

npm install ky@1.11.0

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；權限或餘額錯誤時檢查帳號及帳單；參數錯誤時核對模型、操作和參數值；遇到限流時降低並行數，並遵循回應中提供的重試提示。

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

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

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

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

返回圖像與影片 API 產品頁。

API 介面參考

API 介面參考 · OpenAPI JSON