Authorizationstring · headerrequiredOpen 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. 配置环境变量
export AIUNIVID_BASE_URL=https://aiunivid.com/api/open export AIUNIVID_API_KEY=av_live_xxx - 2. 报价(可选,不扣费)
用与创建相同的请求体调用 POST /v1/videos/generations/quote,读取 data.credits_to_hold。 - 3. 创建任务
POST /v1/videos/generations,必须带 Idempotency-Key。成功返回 202 和任务 id。同一 Key 同一 body 重放不会重复扣费。 - 4. 轮询或接收 Webhook
GET /v1/videos/generations/{id} 直到 status 为 succeeded 或 failed。或在创建时传入 callback_url。成功后使用 result.download_url。
在视频产品站中接入
把 AiuniVid 放在你的后端之后:用户只与你的产品交互,API Key 与任务同步由你的服务处理。
产品前端
提交提示词、模型与参考素材。
你的后端
校验用户、保存业务记录,再调用 AiuniVid。
AiuniVid API
返回 202 与任务 ID,异步生成。
产品结果页
读取你的任务状态并播放成片。
限流规则
每个响应带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset(Unix 秒)。超限返回 429 rate_limit_exceeded。
| 类别 | 端点 | 限额 |
|---|---|---|
| Create endpoints | POST /v1/videos/generations, /quote | 10 requests / minute / key |
| Read endpoints | GET /v1/models, /v1/credits/balance, /v1/videos/generations, /v1/videos/generations/{id} | 60 requests / minute / key |
模型与能力
GET /v1/modelsendpoint{
"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{
"success": true,
"request_id": "req_01JQ9X2B6XK9K4VQY2QZ4H6W3R",
"data": {
"model": "seedance-2.5-text-to-video",
"credits_to_hold": 50,
"currency_note": "credits"
}
}创建生成任务
POST /v1/videos/generationsendpointrequiredmodelenum<string>required| Model ID | Mode | Tier |
|---|---|---|
| seedance-2.5-text-to-video | text-to-video | standard |
| seedance-2.5-image-to-video | image-to-video | standard |
| seedance-2.5-reference-to-video | reference-to-video | standard |
| seedance-2.0-text-to-video | text-to-video | standard |
| seedance-2.0-image-to-video | image-to-video | standard |
| seedance-2.0-reference-to-video | reference-to-video | standard |
| seedance-2.0-fast-text-to-video | text-to-video | fast |
| seedance-2.0-fast-image-to-video | image-to-video | fast |
| seedance-2.0-fast-reference-to-video | reference-to-video | fast |
| seedance-2.0-mini-text-to-video | text-to-video | mini |
| seedance-2.0-mini-image-to-video | image-to-video | mini |
| seedance-2.0-mini-reference-to-video | reference-to-video | mini |
promptstringrequiredimage_urlsstring<uri>[]video_urls / audio_urlsstring<uri>[]durationintegerqualityenum<string>aspect_ratioenum<string>generate_audiobooleancallback_urlstring<uri>metadataobject任务管理
GET /v1/videos/generations/{id}endpointGET /v1/videos/generationsendpoint{
"success": true,
"request_id": "req_xxx",
"data": {
"tasks": [{ "id": "vid_01JQ9X2B6XK9K4VQY2QZ4H6W3R", "status": "succeeded" }],
"next_cursor": null
}
}POST /v1/videos/generations/{id}/cancelendpoint上传参考素材
POST /v1/uploads/presignendpoint{
"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计费语义
网页与 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-EventheaderX-AiuniVid-SignatureheaderNode
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错误处理
根据稳定的 error.code 分支,不要解析 message 文本。500 可用同一 Idempotency-Key 重试。
| HTTP | error.code | 含义 |
|---|---|---|
| 400 | invalid_request | 请求体或字段不合法 |
| 400 | unsupported_model | 模型 ID 不是公开 ID 之一 |
| 401 | invalid_api_key | Key 无效、过期或已吊销 |
| 402 | insufficient_credits | 积分余额不足 |
| 403 | insufficient_scope | Key 缺少所需 scope |
| 403 | task_cancel_not_allowed | 不支持取消任务 |
| 404 | task_not_found | 任务不存在或不属于该 Key |
| 409 | idempotency_conflict | 同 Idempotency-Key 使用了不同请求体 |
| 422 | unsupported_capability | 参数组合超出模型能力 |
| 422 | unsafe_input | 媒体或回调 URL 不是公网 HTTPS 地址 |
| 429 | rate_limit_exceeded | 超出限流阈值 |
| 429 | too_many_concurrent_jobs | 进行中的生成任务超过账号上限 |
| 500 | internal_error | 未分类服务端错误,可用同一 Idempotency-Key 重试 |
机器可读契约:openapi.yaml · api-reference.md · llms.txt