Skip to main content

Open API v1 · Seedance 2.0

把视频生成接进你的产品

AiuniVid Open API 是异步任务网关:创建立即返回任务 ID,网页与 API 共用同一积分账本。开放 Seedance 2.5 与 Seedance 2.0 的文生 / 图生 / 参考三种模式;2.0 另有 Fast、Mini 两档,共 12 个公开模型 ID。

  • Text-to-Video: 纯文本描述生成视频。
  • Image-to-Video: 1–2 张图作为首帧或首尾帧。
  • Reference-to-Video: 图片、视频、音频作为多模态参考。

快速开始

注册用户可在开发者中心自行创建 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。或在创建时传入 callback_url。成功后使用 result.download_url。

在视频产品站中接入

把 AiuniVid 放在你的后端之后:用户只与你的产品交互,API Key 与任务同步由你的服务处理。

01

产品前端

提交提示词、模型与参考素材。

02

你的后端

校验用户、保存业务记录,再调用 AiuniVid。

03

AiuniVid API

返回 202 与任务 ID,异步生成。

04

产品结果页

读取你的任务状态并播放成片。

实现边界:不要让前端直接请求 Open API,也不要把 API Key、回调签名密钥或计费判断暴露给客户端。

认证与 Scope

Authorizationstring · headerrequired
所有端点需要 Bearer Token:Authorization: Bearer $AIUNIVID_API_KEY。
Idempotency-Keystring · headerrequired
创建任务时必填。推荐 UUID。同一 Key 同一 body 在 24 小时内重放返回首次结果;同一 Key 不同 body 返回 409 idempotency_conflict。
Scope权限范围
video:createCreate and quote generation tasks.
video:readRead tasks, models, and credit balance.
files:writeRequest presigned upload URLs for reference media.

限流规则

每个响应带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset(Unix 秒)。超限返回 429 rate_limit_exceeded。

类别端点限额
Create endpointsPOST /v1/videos/generations, /quote10 requests / minute / key
Read endpointsGET /v1/models, /v1/credits/balance, /v1/videos/generations, /v1/videos/generations/{id}60 requests / minute / key

模型与能力

GET /v1/modelsendpoint
返回当前 Key 可用的公开模型,以及 duration、quality、aspect_ratio 和能力标记。创建前用此端点校验产品侧可展示的选项。Seedance 2.5、Fast 与 Mini 不支持 1080p。
{
  "success": true,
  "request_id": "req_xxx",
  "data": {
    "models": [
      {
        "id": "seedance-2.0-text-to-video",
        "name": "Seedance 2.0 Text-to-Video",
        "mode": "text-to-video",
        "tier": "standard",
        "durations": [5, 8, 10],
        "aspect_ratios": ["16:9", "9:16", "1:1"],
        "qualities": ["480p", "720p", "1080p"],
        "capabilities": {
          "text_to_video": true,
          "generate_audio": true,
          "max_images": 0,
          "max_videos": 0,
          "max_audios": 0
        }
      }
    ]
  }
}

生成报价

POST /v1/videos/generations/quoteendpoint
使用与创建任务相同的请求体预估积分。不创建任务、不冻结积分;返回 data.credits_to_hold。报价与创建使用同一计费公式。
{
  "success": true,
  "request_id": "req_01JQ9X2B6XK9K4VQY2QZ4H6W3R",
  "data": {
    "model": "seedance-2.5-text-to-video",
    "credits_to_hold": 50,
    "currency_note": "credits"
  }
}

创建生成任务

POST /v1/videos/generationsendpointrequired
异步创建视频任务;成功返回 202 与任务对象。右侧监视器可切换模型与语言示例。
modelenum<string>required
使用下列公开模型 ID,不要使用上游别名。
Model IDModeTier
seedance-2.5-text-to-videotext-to-videostandard
seedance-2.5-image-to-videoimage-to-videostandard
seedance-2.5-reference-to-videoreference-to-videostandard
seedance-2.0-text-to-videotext-to-videostandard
seedance-2.0-image-to-videoimage-to-videostandard
seedance-2.0-reference-to-videoreference-to-videostandard
seedance-2.0-fast-text-to-videotext-to-videofast
seedance-2.0-fast-image-to-videoimage-to-videofast
seedance-2.0-fast-reference-to-videoreference-to-videofast
seedance-2.0-mini-text-to-videotext-to-videomini
seedance-2.0-mini-image-to-videoimage-to-videomini
seedance-2.0-mini-reference-to-videoreference-to-videomini
promptstringrequired
1–10,000 个字符。参考模式使用 @image1、@video1、@audio1 按数组顺序指代素材。
image_urlsstring<uri>[]
必须是服务端可访问的公网 HTTPS URL。文生模式不支持;图生必须 1–2 张(1 张为首帧,2 张为首尾帧);参考模式 Seedance 2.0 最多 9 张,Seedance 2.5 最多 30 张。
video_urls / audio_urlsstring<uri>[]
仅参考模式。Seedance 2.0 各最多 3 个公网 HTTPS URL,且音频不能作为唯一参考输入。Seedance 2.5 各最多 10 个,并支持纯音频。以 GET /v1/models 的 capabilities 为准。
durationinteger
Seedance 2.5 为 4–30 秒,Seedance 2.0 系列为 4–15 秒,默认 5。以 GET /v1/models 返回值为准。
qualityenum<string>
480p / 720p / 1080p,默认 720p。Seedance 2.5、Fast 与 Mini 传入 1080p 会返回 422 unsupported_capability。
aspect_ratioenum<string>
16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive.
generate_audioboolean
默认 true,计入报价。
callback_urlstring<uri>
可选公网 HTTPS 地址。任务进入终态时 POST 任务对象,需校验签名。
metadataobject
可选,仅允许 string 值,每项最多 500 字符,会随任务对象返回。

任务管理

GET /v1/videos/generations/{id}endpoint
轮询直到 status 为 succeeded 或 failed。任务提交后不可取消,需等待完成或失败后退款。成功时读取 result.download_url;该 URL 是平台转存后的稳定地址,不是上游临时链。状态机:queued → processing → succeeded | failed。
GET /v1/videos/generationsendpoint
按创建时间倒序列出任务。查询参数:limit(1–100,默认 20)、cursor、status。data.next_cursor 为 null 表示最后一页。
{
  "success": true,
  "request_id": "req_xxx",
  "data": {
    "tasks": [{ "id": "vid_01JQ9X2B6XK9K4VQY2QZ4H6W3R", "status": "succeeded" }],
    "next_cursor": null
  }
}
POST /v1/videos/generations/{id}/cancelendpoint
不支持取消。提交后的任务会一直跑到成功或失败;失败会自动退回冻结积分。调用该接口返回 403 task_cancel_not_allowed。

上传参考素材

POST /v1/uploads/presignendpoint
提交 filename、content_type 和可选 purpose。将文件 PUT 到 data.upload_url(带上返回的 headers),再把 data.public_url 写入 image_urls / video_urls / audio_urls。需要 files:write scope。
{
  "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"
  }
}

积分余额

GET /v1/credits/balanceendpoint
返回 available_credits 与 frozen_credits。创建前可先报价再决定是否提交。

计费语义

网页与 API 对同一用户使用同一加价。1 积分 = $0.01。

阶段行为
quote不算账,返回 credits_to_hold
create冻结 credits_reserved
succeeded结算 credits_settled
failed / cancelled释放冻结,credits_refunded

Webhooks

创建时传入 callback_url。任务进入 succeeded / failed / cancelled 时 POST 完整任务对象。

X-AiuniVid-Eventheader
video.completed · video.failed · video.cancelled
X-AiuniVid-Signatureheader
格式 t=<unix 秒>,v1=<hex>。signed_payload = "{t}." + raw_body,v1 为 HMAC-SHA256(secret, signed_payload) 的 hex。时间戳超过 5 分钟应拒绝。请先读取原始 body 再 JSON.parse。

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 会按 1s / 2s / 4s / 8s … 指数退避重试,最长 24 小时。请始终返回 2xx 表示已接收。

高级兼容路径

主路径是 /v1/videos/generations。若你已按 BytePlus content[] 对接,可继续使用 /v1/contents/generations/tasks(及对应 quote)。新集成请不要使用这条路径。

POST /v1/contents/generations/tasksendpoint
model 使用内部档位 seedance-2.5 / seedance-2.0 / seedance-2.0-fast / seedance-2.0-mini,content 数组包含 text / image_url / video_url / audio_url。计费与主路径相同,仍需要 Idempotency-Key。

错误处理

根据稳定的 error.code 分支,不要解析 message 文本。500 可用同一 Idempotency-Key 重试。

HTTPerror.code含义
400invalid_request请求体或字段不合法
400unsupported_model模型 ID 不是公开 ID 之一
401invalid_api_keyKey 无效、过期或已吊销
402insufficient_credits积分余额不足
403insufficient_scopeKey 缺少所需 scope
403task_cancel_not_allowed不支持取消任务
404task_not_found任务不存在或不属于该 Key
409idempotency_conflict同 Idempotency-Key 使用了不同请求体
422unsupported_capability参数组合超出模型能力
422unsafe_input媒体或回调 URL 不是公网 HTTPS 地址
429rate_limit_exceeded超出限流阈值
429too_many_concurrent_jobs进行中的生成任务超过账号上限
500internal_error未分类服务端错误,可用同一 Idempotency-Key 重试

机器可读契约:openapi.yaml · api-reference.md · llms.txt

API 文档 | AiuniVid