文档

支持的端点

• POST/api/v3/contents/generations/tasks创建视频生成任务，立即返回 task ID（异步生成）
• GET/api/v3/contents/generations/tasks/{id}查询单个任务（含 status / content.video_url / usage 等）
• GET/api/v3/contents/generations/tasks查询任务列表（page_num / page_size + filter.* 过滤）
• DELETE/api/v3/contents/generations/tasks/{id}删除 / 取消任务

字段顺序与 Volcengine Ark 官方一致。content数组的子元素结构见下方"content 子元素详解"。

content 子元素详解

content 数组按顺序保留语义。至少需包含一项 type=text。其它三种类型可选，多张参考图 / 视频 / 音频组合使用以控制生成结果。

创建任务 · 响应体

{
  "id": "vt-016569a13c00646194323164"
}

{
  "id": "vt-016569a13c00646194323164",
  "model": "doubao-seedance-2.0",
  "status": "succeeded",
  "content": {
    "video_url": "https://tos-cn-beijing.volces.com/path/to/plain-video.mp4?X-Tos-Expires=86400..."
  },
  "usage": {
    "prompt_tokens": 1290,
    "completion_tokens": 35840,
    "total_tokens": 37130
  },
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 8,
  "seed": 12345,
  "service_tier": "default",
  "generate_audio": true,
  "created_at": 1748945523,
  "updated_at": 1748945910
}

默认建议直接使用content.video_url下载解密后的 mp4。如果需要自行处理上游加密文件，查询任务时同时传video_url_mode=upstream和include_decryption=1，响应会返回当前视频专用的data_key_b64。

• · 下载 `content.video_decryption.upstream_video_url` 得到加密文件。
• · Base64 解码 `data_key_b64`，作为 AES-256-GCM key。
• · 加密文件前 12 字节是 nonce，其余部分是 ciphertext + tag。
• · 上游 TOS URL 通常约 24 小时过期；过期后重新查询任务获取新的 URL 和解密材料。
• · 平台不会返回上游 API key / AK / SK / RSA 私钥；`data_key_b64` 只能解密当前视频，不能用于生成视频。

# pip install requests cryptography
import base64
import requests
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

BASE_URL = "https://www.aiapigo.com/api/v3"
API_KEY = "sk-ai-***"
TASK_ID = "vt-016569a13c00646194323164"

# 1) 查询任务，并要求返回上游加密 TOS URL 和单视频解密材料
task = requests.get(
    f"{BASE_URL}/contents/generations/tasks/{TASK_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "video_url_mode": "upstream",
        "include_decryption": "1",
    },
    timeout=30,
).json()

if task["status"] != "succeeded":
    raise RuntimeError(f"task is not succeeded: {task['status']}")

dec = task["content"]["video_decryption"]

# 2) 下载上游加密文件。该 URL 通常约 24 小时过期
encrypted_file = requests.get(dec["upstream_video_url"], timeout=300).content

# 3) 解密。文件布局为 nonce || ciphertext || tag
key = base64.b64decode(dec["data_key_b64"])
nonce = encrypted_file[:12]
ciphertext_and_tag = encrypted_file[12:]

plaintext = AESGCM(key).decrypt(nonce, ciphertext_and_tag, None)
with open("video.mp4", "wb") as f:
    f.write(plaintext)

print("saved to video.mp4")

任务状态机（status 字段）

异步：客户端用 task ID 轮询；平台后台同步上游状态并保存，查询接口返回平台缓存状态， 状态值与 Volcengine Ark 完全一致。

• pending任务已提交，等待调度。
• queued已进入排队序列，等待资源。
• running正在生成中。
• succeeded生成成功。content.video_url 为视频下载地址，usage 字段携带 token 用量。本次扣费。
• failed生成失败。error 字段携带错误信息。不扣费。
• cancelled任务已被取消。不扣费。
• expired任务已过期或超时。不扣费。

翻页与过滤参数与 Volcengine 上游一致；响应 schema 为{ total, items: [...] }。

错误响应（Ark 信封）

{
  "error": {
    "code":    "insufficient_balance",
    "message": "余额不足，请充值后重试"
  }
}

• 401missing_key / invalid_keyAuthorization header 缺失或无效
• 402insufficient_balance余额不足以承担预估的最大成本
• 404model_not_found / task_not_foundmodel 未上线 / task 不存在或非本账号
• 400missing_model / model_kind_mismatch / invalid_upstream_parametermodel 字段缺失、不是视频模型，或请求参数不符合视频生成要求
• 400reference_video_duration_exceeded / reference_audio_too_short / invalid_asset_url参考视频时长超限、参考音频过短或素材不可用
• 400input_text_sensitive / input_image_sensitive / input_image_privacy_information提示词、参考图或真人/隐私内容未通过安全校验
• 400output_video_sensitive / output_audio_sensitive / content_policy_violation生成结果或兜底内容安全校验未通过
• 429upstream_rate_limited请求过于频繁，请降低并发并稍后重试
• 502upstream_error / upstream_internal_error视频生成服务暂时不可用
• 502no_account_available视频生成账号池暂无可用账号（配额不足或全部禁用）

完整 API 参考、限流、SLA 等内容在编写中。如急需可联系support@aiapigo.com。

视频生成常见错误处理建议

视频任务创建失败时，接口会同步返回{ error: {...} }；任务生成失败时，查询任务和列表接口会在error/failure_reason里返回同样结构。外层信封保持不变；平台会细分error.code并额外补充field/input_type等诊断字段，不影响官方字段解析。

{
  "error": {
    "code": "input_text_sensitive",
    "type": "content_policy_violation",
    "message": "提示词未通过内容安全校验，任务创建失败。",
    "suggestion": "请调整 content[0] 中的敏感文本后重试；可弱化暴力、胁迫、隐私、成人或高风险情节。",
    "retryable": false,
    "field": "content[0]",
    "input_type": "text",
    "upstream_code": "InputTextSensitiveContentDetected",
    "upstream_request_id": "0217853170174640e9e2f2120f1f78e103cd745191b1689d97bd8"
  }
}

{
  "id": "vt-016569a13c00646194323164",
  "model": "doubao-seedance-2.0",
  "status": "failed",
  "error": {
    "code": "output_video_sensitive",
    "type": "content_policy_violation",
    "message": "生成视频未通过内容安全校验，任务生成失败。",
    "suggestion": "生成结果触发内容安全校验，请调整提示词、参考图或参考视频后重试，弱化暴力、胁迫、隐私、成人或高风险情节。",
    "retryable": false,
    "input_type": "generated_video",
    "upstream_code": "OutputVideoSensitiveContentDetected",
    "upstream_request_id": "021785221514026464ab88fe358ba5cca4a17963dcac1bf1ffcdc"
  },
  "failure_reason": {
    "code": "output_video_sensitive",
    "type": "content_policy_violation",
    "message": "生成视频未通过内容安全校验，任务生成失败。",
    "suggestion": "生成结果触发内容安全校验，请调整提示词、参考图或参考视频后重试，弱化暴力、胁迫、隐私、成人或高风险情节。",
    "retryable": false,
    "input_type": "generated_video",
    "upstream_code": "OutputVideoSensitiveContentDetected",
    "upstream_request_id": "021785221514026464ab88fe358ba5cca4a17963dcac1bf1ffcdc"
  }
}

{
  "error": {
    "code": "reference_audio_too_short",
    "type": "invalid_request_error",
    "message": "参考音频时长过短，任务创建失败。",
    "suggestion": "请将 content[6] 的 reference_audio 音频时长调整到至少 1.8 秒，或移除该音频后重试。",
    "retryable": false,
    "upstream_code": "InvalidParameter",
    "upstream_request_id": "021785221514026464ab88fe358ba5cca4a17963dcac1bf1ffcdc"
  }
}