影片生成

POST /v1/videos · GET /v1/videos/{id} · DELETE /v1/videos/{id}

根據文字提示詞生成短影片,可選傳入首/尾參考幀控制畫面。這是業界標準 create + poll 形態的非同步任務 API:POST /v1/videos 約 2 秒返回任務物件,輪詢至完成;加上 Prefer: wait 標頭可讓快速生成一次呼叫直達結果。Seedance 系列模型,一把 API key,計費與其他端點一致。

端點與任務生命週期

一個任務資源,四種操作。任務狀態流轉:queued → in_progress → 終態之一(completed、failed 或 cancelled)。建立回應自帶 status_url / cancel_url 連結,無需手動拼 URL。

同步糖 —— Prefer: wait

在建立請求上加 Prefer: wait 或 Prefer: wait=N 標頭(N 限制在 1..60 秒),閘道會保持連線等待。任務在視窗內完成則直接返回終態物件——含影片 URL 與用量,無需輪詢;未在視窗內完成則優雅降級:返回目前狀態物件(不報錯,任務照常執行),繼續正常輪詢即可。

請求主體

可用模型

模型可用性取決於你的部署。透過 GET /v1/videos/models取得即時、合規感知的完整清單(含每模型解析度/片長約束與價格)。目前陣容:

價格:USD / 1M video tokens。seedance-1-5-pro-251215 開音軌(generate_audio: true,預設)$2.4、關音軌 $1.2;其餘模型按解析度檔單一費率。

video token 與定價

影片按 video token 計費,由實際輸出推導:tokens ≈ 寬 × 高 × 24 fps × 秒 / 1024。費率按每 1M video tokens 計,以實際生效參數(completed 任務中回傳)為準——因此 ratio: "adaptive" 與 duration: -1 都按模型實際產出計費。

直觀錨點(seedance-1-5-pro-251215 有聲):480p / 16:9 / 4 秒 ≈ 40.6K video tokens ≈ $0.10;720p / 5 秒 ≈ 108.9K tokens ≈ $0.26。

計費

僅成功才計費:任務首次到達 completed 時結算一次,按回傳的 video token 用量計價。失敗任務(含內容審核拒絕)與取消任務一律不收費——上游錯誤原樣透傳,便於定位原因。

範例 —— curl 一步到位(Prefer: wait)

curl https://synthorai.io/v1/videos \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{
    "model": "seedance-1-0-pro-fast-251015",
    "prompt": "A corgi puppy chasing a butterfly across a meadow, cinematic",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4
  }'

# Finished inside the wait window → the terminal object comes straight back:
{
  "id": "vid_6091d8d1af805818b1470488",
  "object": "video",
  "model": "seedance-1-0-pro-fast-251015",
  "status": "completed",
  "data": [{ "url": "https://…tos….mp4?…" }],
  "usage": { "completion_tokens": 40594, "total_tokens": 40594 },
  "resolution": "480p", "ratio": "16:9", "duration": 4, "fps": 24,
  "seed": 34142
}
# Not done in time → the current status object is returned instead (no error,
# the task keeps running) — continue polling status_url as usual.

範例 —— curl 建立 + 輪詢

# 1) Create — returns in ~2 s with a queued task object
curl https://synthorai.io/v1/videos \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-5-pro-251215",
    "prompt": "A corgi puppy chasing a butterfly across a meadow, cinematic",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  }'

{
  "id": "vid_6091d8d1af805818b1470488",
  "object": "video",
  "model": "seedance-1-5-pro-251215",
  "status": "queued",
  "created_at": 1784619862,
  "status_url": "https://synthorai.io/v1/videos/vid_6091d8d1af805818b1470488",
  "cancel_url": "https://synthorai.io/v1/videos/vid_6091d8d1af805818b1470488"
}

# 2) Poll until status is terminal (completed | failed | cancelled)
curl https://synthorai.io/v1/videos/vid_6091d8d1af805818b1470488 \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY"

{
  "id": "vid_6091d8d1af805818b1470488",
  "object": "video",
  "model": "seedance-1-5-pro-251215",
  "status": "completed",
  "data": [{ "url": "https://…tos….mp4?…" }],
  "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
  "resolution": "720p", "ratio": "16:9", "duration": 5, "fps": 24,
  "seed": 34142, "generate_audio": true
}

# 3) Download the video — the URL is pre-signed (no auth header) and expires
#    in ~24 h: fetch promptly and re-host if you need it long-term.
curl -o out.mp4 "https://…tos….mp4?…"

範例 —— Python(requests)

import time
import requests

BASE = "https://synthorai.io/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

task = requests.post(f"{BASE}/videos", headers=HEADERS, json={
    "model": "seedance-1-5-pro-251215",
    "prompt": "A corgi puppy chasing a butterfly across a meadow, cinematic",
    "resolution": "720p",
    "duration": 5,
}).json()

while task["status"] not in ("completed", "failed", "cancelled"):
    time.sleep(5)
    task = requests.get(task["status_url"], headers=HEADERS).json()

if task["status"] == "completed":
    url = task["data"][0]["url"]  # pre-signed, valid ~24 h — re-host promptly
    with open("out.mp4", "wb") as f:
        f.write(requests.get(url).content)
else:
    print(task["error"])  # provider code + message, passed through verbatim

範例 —— Node(fetch)

import fs from "node:fs";

const BASE = "https://synthorai.io/v1";
const HEADERS = { Authorization: `Bearer ${process.env.SYNTHORAI_API_KEY}` };

let task = await (await fetch(`${BASE}/videos`, {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "seedance-1-5-pro-251215",
    prompt: "A corgi puppy chasing a butterfly across a meadow, cinematic",
    resolution: "720p",
    duration: 5,
  }),
})).json();

while (!["completed", "failed", "cancelled"].includes(task.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  task = await (await fetch(task.status_url, { headers: HEADERS })).json();
}

if (task.status === "completed") {
  const url = task.data[0].url; // pre-signed, valid ~24 h — re-host promptly
  fs.writeFileSync("out.mp4", Buffer.from(await (await fetch(url)).arrayBuffer()));
} else {
  console.error(task.error); // provider code + message, passed through verbatim
}

冪等性

傳 X-Idempotency-Key 請求標頭讓重試安全:相同 key 的重複請求返回 409,而不會二次建立(和二次計費)任務。影片生成慢、易逾時重試,這能防止重複扣費。