把影片生成接進你的產品

快速開始

註冊使用者可在工作台的「API › API 金鑰」自行建立 av_live_ 金鑰，無需稽核。金鑰只在建立時展示一次，請儲存在服務端。

1. 1. 配置環境變數
   複製

   export AIUNIVID_BASE_URL=https://aiunivid.com/api/open
   export AIUNIVID_API_KEY=av_live_xxx

2. 2. 報價（可選，不扣費）
   用與建立相同的請求體呼叫 POST /v1/videos/generations/quote，讀取 data.credits_to_hold。
3. 3. 建立任務
   POST /v1/videos/generations，必須帶 Idempotency-Key。成功返回 202 和任務 id。同一 Key 同一 body 重放不會重複扣費。
4. 4. 輪詢或接收 Webhook
   GET /v1/videos/generations/{id} 直到 status 為 succeeded、failed 或 cancelled。或在建立時傳入 callback_url。成功後使用 result.download_url。

在影片產品站中接入

把 AiuniVid 放在你的後端之後：使用者只與你的產品互動，API Key 與任務同步由你的服務處理。

MCP：讓 AI 助手直接出片

通過 Model Context Protocol，把 Claude、ChatGPT、Cursor、VS Code 等 MCP 用戶端連到 AiuniVid。助手可以替你查模型、報價、建立和查詢影片，還能生成角色圖片；消耗的是你的點數，價格、限流和請求日誌都與開放 API 相同。

服務地址

https://aiunivid.com/api/mcp

在用戶端裡新增服務地址，用戶端會開啟瀏覽器：登入 AiuniVid 並點「允許」即可，不用複製 API Key。每次授權都會成為一條連線，可在「API › MCP 連線」裡隨時撤銷。

接入你的用戶端

https://aiunivid.com/api/mcp

https://aiunivid.com/api/mcp

claude mcp add --transport http --scope user aiunivid https://aiunivid.com/api/mcp

codex mcp add aiunivid --url https://aiunivid.com/api/mcp
codex mcp login aiunivid

{
  "mcpServers": {
    "aiunivid": { "url": "https://aiunivid.com/api/mcp" }
  }
}

gemini mcp add --transport http --scope user aiunivid https://aiunivid.com/api/mcp

{
  "mcp": {
    "aiunivid": { "type": "remote", "url": "https://aiunivid.com/api/mcp", "enabled": true }
  }
}

{
  "servers": {
    "aiunivid": { "type": "http", "url": "https://aiunivid.com/api/mcp" }
  }
}

https://aiunivid.com/api/mcp

沒有瀏覽器時：用 API Key

指令碼、伺服器等打不開登入頁的環境，可以改用開放 API 的 Key（需有 video:create 和 video:read 權限），放在 Authorization 請求頭裡。

claude mcp add --transport http aiunivid https://aiunivid.com/api/mcp \
  --header "Authorization: Bearer $AIUNIVID_API_KEY"

為什麼用託管服務、每支影片多少錢、和自建有什麼不同，見Seedance MCP 服務指南

工具

認證與 Scope

限流規則

每個響應帶 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（Unix 秒）。超限返回 429 rate_limit_exceeded。限額按 Key 與權限類別計：所有讀介面共用同一額度，同時跟蹤多個任務時請用列表介面批次查詢或使用回呼，不要逐個高頻輪詢。

模型與能力

{
  "success": true,
  "request_id": "req_xxx",
  "data": {
    "models": [
      {
        "id": "byteplus-seedance-2.0-text-to-video",
        "name": "BytePlus Seedance 2.0 Text-to-Video",
        "mode": "text-to-video",
        "tier": "standard",
        "durations": [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
        "aspect_ratios": ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "adaptive"],
        "qualities": ["480P", "720P", "1080P", "4K"],
        "capabilities": {
          "text_to_video": true,
          "image_to_video": false,
          "reference_to_video": false,
          "generate_audio": true,
          "max_images": 0,
          "max_videos": 0,
          "max_audios": 0,
          "audio_only": false,
          "draft_mode": false
        }
      }
    ]
  }
}

生成報價

{
  "success": true,
  "request_id": "req_01JQ9X2B6XK9K4VQY2QZ4H6W3R",
  "data": {
    "model": "byteplus-seedance-2.5-text-to-video",
    "credits_to_hold": 187,
    "currency_note": "credits"
  }
}

建立生成任務

任務管理

{
  "success": true,
  "request_id": "req_xxx",
  "data": {
    "tasks": [{ "id": "vid_01JQ9X2B6XK9K4VQY2QZ4H6W3R", "status": "succeeded" }],
    "next_cursor": null
  }
}

真人與角色

上傳的圖片或影片裡有可識別的真人臉時，會被模型的稽核拒絕，建立請求返回 422 real_person_detected（不扣費，原樣重試仍會失敗）。想讓影片裡出現寫實的人物，有三種合規做法：

1. 用這裡生成的圖。用 POST /v1/images/generations 生成的圖片，在返回的 trusted_until 之前（24 小時）放進 image_urls，即使是寫實人像也不會被當成真人照片拒絕；過期後按普通上傳圖處理。
2. 本人核驗過的形象。要出現某位真實的人，需要本人在網頁端完成活體核驗，再把照片加為核驗形象。GET /v1/characters 列出你核驗過的形象和你在網頁端建的虛構角色。把返回的 uri（asset://…）放進參考生影片模型的 image_urls，提示詞裡用 @image1、@image2 指代，不要把 asset ID 本身寫進提示詞。支援的模型在 GET /v1/models 裡 capabilities.asset_references 為 true。
3. 插畫或風格化的角色不受影響。

生成過程中失敗的任務，error.reason 會給出機器可讀的原因（如 real_person、sensitive_prompt），據此決定是改輸入還是重試。

生成圖片

POST /v1/images/generations：Seedream 5.0 文生圖，同步返回，按張扣點數，與網頁端同價。需要 video:create 權限和 Idempotency-Key，計入建立類限流。每張圖返回穩定的 url 和 trusted_until（Unix 秒）。

請求欄位：model（byteplus-seedream-5.0-pro 或 byteplus-seedream-5.0-lite，必填）、prompt（3–2,400 字元，必填）、size（Pro：1K / 2K；Lite：2K / 3K / 4K；預設最小檔）、aspect_ratio（1:1、16:9、9:16、4:3、3:4）、name（自己備註用，最多 80 字元）。提示詞被拒返回 422 prompt_rejected，不扣費。

上傳參考素材

{
  "success": true,
  "request_id": "req_xxx",
  "data": {
    "upload_url": "https://aiunivid.com/api/open/v1/uploads/put?key=api-uploads/...&sig=...",
    "public_url": "https://cdn.example.com/api-uploads/user/file.png",
    "expires_at": 1761314644,
    "headers": { "Content-Type": "image/png" },
    "method": "PUT"
  }
}

點數餘額

價格與折扣

以 720P · 10 秒、純文生為例，單位為點數（1 點數 = 0.01 美元）。實際扣費以報價介面 POST /v1/videos/generations/quote 為準；帳號如有專屬折扣，報價已經算在內。

計費語義

網頁與 API 價格相同，扣的是同一份點數。1 點數 = $0.01。

Webhooks

建立時傳入 callback_url。任務進入 succeeded / failed / cancelled 時 POST 完整任務物件。

Node

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAiuniVidSignature(header, rawBody, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((item) => item.split("="))
  );
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > 300) throw new Error("Signature timestamp is stale");

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  if (
    !timingSafeEqual(Buffer.from(parts.v1, "utf8"), Buffer.from(expected, "utf8"))
  ) {
    throw new Error("Invalid signature");
  }
}

Python

import hmac, hashlib, time

def verify_aiunivid_signature(header: str, raw_body: str, secret: str) -> None:
    parts = dict(item.split("=", 1) for item in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        raise ValueError("Signature timestamp is stale")
    expected = hmac.new(
        secret.encode(),
        f'{parts["t"]}.{raw_body}'.encode(),
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(parts["v1"], expected):
        raise ValueError("Invalid signature")

投遞超時 10 秒。超時或非 2xx 會自動重試：間隔從約 1 分鐘開始逐步拉長，最長 1 小時一次，持續 24 小時。請始終返回 2xx 表示已接收。同一事件可能送達不止一次，請按任務 id 與事件去重。建議同時以較低頻率輪詢兜底。

錯誤處理

根據穩定的 error.code 分支，不要解析 message 文字。500 可用同一 Idempotency-Key 重試。

批次生產系列影片

一個短影片系列，是許多共用同一批角色與場景的小任務。下面四個做法讓它保持一致、成本可預期。

1. 角色只上傳一次。用 /v1/uploads/presign 上傳角色圖，之後系列裡的每個請求都在 image_urls 裡傳同一個 public_url，並在 prompt 裡用 @image1 指代它。可識別的真人臉會被所有模型拒絕，請使用生成或繪製的角色。
2. 每個鏡頭一個請求。一個請求只講一個節拍，鏡頭在你自己的剪輯流程裡拼接。每個鏡頭用自己的 Idempotency-Key：只有在沒收到響應（例如網路中斷）時才用原 Key 重放；鏡頭生成失敗後要重試，必須換一個新 Key——同一 Key 在 24 小時內重放，返回的是第一次的結果。
3. 先報價再批次提交。把整批請求體先發到 /v1/videos/generations/quote，與 /v1/credits/balance 返回的 available_credits 對比，餘額不足就在提交前停下；報價與扣費用的是同一個公式。建立介面限流為每個 Key 每分鐘 10 次，大批次要勻速提交。
4. 用 Webhook 收結果，不要高頻輪詢。建立時傳 callback_url；讀介面限流為每個 Key 每分鐘 60 次，一批任務各自輪詢很快就會觸頂。失敗鏡頭凍結的點數會自動釋放。

怎麼讓同一個角色在各個鏡頭裡保持一致，見 角色跨鏡頭一致指南。