Seedance 视频生成 API 接入文档

🌐 梦想家接入：https://api.alimxj.com

📋 概述

火山方舟 Seedance 视频生成 API 提供多种视频生成模式，支持文生视频、图生视频及多素材组合生成：

模式	说明	content 类型
文生视频	纯文本提示词生成视频	`text`
图生视频	参考图片 + 文本生成视频	`text` + `image_url`
多素材组合	图片 + 视频 + 音频 + 文本	`text` + `image_url` + `video_url` + `audio_url`

API 采用火山引擎标准接口协议，支持 Bearer Token 和 HMAC-SHA256 签名两种认证方式。

🔑 认证方式

平台支持双认证模式，可根据安全需求选择：

方式 1：Bearer Token（推荐）

适合快速接入，直接在请求头中携带 API Key：

Authorization: Bearer YOUR_API_KEY

方式 2：HMAC-SHA256 签名（高安全性）

与火山引擎完全兼容的签名认证，提供更高的安全性：

✅ 防请求篡改
✅ 防重放攻击
✅ 与火山引擎 SDK 兼容

Authorization: HMAC-SHA256 Credential={AccessKeyId}/{Date}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}
X-Date: {YYYYMMDDTHHMMSSZ}

详见 HMAC-SHA256 签名认证章节。

🌐 Base URL

本服务通过独立 API 域名对外提供，Host 不带端口：

接入环境	Base URL	Host 头
梦想家	`https://api.alimxj.com/v3`	`api.alimxj.com`

📡 API 端点

1. 创建视频生成任务

POST /contents/generations/tasks

完整路径：https://api.alimxj.com/v3/contents/generations/tasks

创建异步视频生成任务，返回任务 ID 用于后续状态查询。

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，支持：`doubao-seedance-2-5-betydance`、`doubao-seedance-2-0-fast-260129-betydance`、`doubao-seedance-2-0-mini-260616-betydance`
`content`	array	是	内容数组，支持 text / image_url / video_url / audio_url 四种类型
`omni_reference_task_type`	string	否	任务类型引导（仅 Seedance 2.5）。可选值：`auto`（默认，自动识别）、`reference`（全模态参考）、`edit`（视频编辑）、`extend`（视频延长）。首帧/首尾帧生视频不需要此参数，直接用 role 区分
`ratio`	string	否	视频比例，可选值：`16:9`、`9:16`、`1:1`、`4:3`、`3:4`、`21:9`、`adaptive`（自适应，用于视频编辑/续写），默认 `16:9`
`duration`	integer	否	生成视频总时长（秒）
`resolution`	string	否	分辨率，可选值：`480p`、`720p`、`1080p`
`generate_audio`	boolean	否	是否自动生成配音，默认 `true`
`watermark`	boolean	否	是否添加平台水印，默认 `false`

content 数组类型

1. 文本提示词 (type = text)

参数	类型	必填	说明
`type`	string	是	固定值：`text`
`text`	string	是	分镜文案。用图片N / 视频N / 音频N 引用素材（如图片1、视频1、音频1，按 content 数组顺序从 1 编号）

2. 参考图片 (type = image_url)

参数	类型	必填	说明
`type`	string	是	固定值：`image_url`
`image_url.url`	string	是	图片 URL（HTTP/HTTPS 或 Base64）
`role`	string	否	图片的位置或用途。图生视频-首帧：`first_frame` 或不填；图生视频-首尾帧：首帧 `first_frame`，尾帧 `last_frame`（必填）；全模态参考生视频：`reference_image`（必填）。所有版本（2.5/2.0/1.5/1.0）通用

3. 参考视频 (type = video_url)

参数	类型	必填	说明
`type`	string	是	固定值：`video_url`
`video_url.url`	string	是	公网可访问 MP4 视频链接
`role`	string	是	固定值：`reference_video`

4. 参考音频 (type = audio_url)

参数	类型	必填	说明
`type`	string	是	固定值：`audio_url`
`audio_url.url`	string	是	公网可访问 MP3 音频链接
`role`	string	是	固定值：`reference_audio`

约束说明：

参考图片最多 30 张（Seedance 2.5），9 张（Seedance 2.0）
参考视频最多 10 个（Seedance 2.5），3 个（Seedance 2.0）
参考音频最多 10 个（Seedance 2.5），3 个（Seedance 2.0）
纯文生视频仅需 1 个 type: "text" 元素
图生视频-首帧/首尾帧、全模态参考生视频 为互斥场景，不可混用

请求示例

示例 1：纯文生视频

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "一只小猫在草地上追蝴蝶，阳光明媚，4K画质"
      }
    ],
    "ratio": "16:9",
    "duration": 5
  }'

示例 2：图生视频（单张参考图片）

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "图片1古风少女站在桃花树下，镜头环绕人物旋转，花瓣随风飘落"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/girl-portrait.jpg"},
        "role": "reference_image"
      }
    ],
    "duration": 5,
    "ratio": "9:16"
  }'

示例 3：多素材组合（图片 + 视频 + 音频）

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "图片1里的小猫在图片2的花园里奔跑，配合音频1作为背景音乐"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/cat.jpg"},
        "role": "reference_image"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/garden.jpg"},
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/reference.mp4"},
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://example.com/bgm.mp3"},
        "role": "reference_audio"
      }
    ],
    "duration": 7,
    "ratio": "16:9",
    "generate_audio": true
  }'

示例 4：Base64 图片输入

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "图片1海边落日，海面波光流动，氛围感电影色调"
      },
      {
        "type": "image_url",
        "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."},
        "role": "reference_image"
      }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'

示例 5：首帧生视频（所有版本通用）

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "图中女孩对着镜头说"茄子"，360度环绕运镜"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first-frame.jpg"},
        "role": "first_frame"
      }
    ],
    "ratio": "adaptive",
    "duration": 5,
    "generate_audio": true
  }'

示例 6：首尾帧生视频（所有版本通用）

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "女孩从站立姿势变为挥手，动作流畅自然"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first.jpg"},
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/last.jpg"},
        "role": "last_frame"
      }
    ],
    "ratio": "adaptive",
    "duration": 5,
    "generate_audio": true
  }'

示例 7：全模态参考生视频（Seedance 2.5） — 使用 role: "reference_image" + omni_reference_task_type

curl -X POST "https://api.alimxj.com/v3/contents/generations/tasks" \
  -H "Authorization: Bearer *** \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-betydance",
    "content": [
      {
        "type": "text",
        "text": "图片1里的小猫在花园里奔跑"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/cat.jpg"},
        "role": "reference_image"
      }
    ],
    "omni_reference_task_type": "reference",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

成功响应

{
  "output": {
    "task_id": "a72f41c9-12b3-4e5f-8d9c-xxxxxxxxxxxx",
    "task_status": "PENDING"
  },
  "request_id": "81df29ac-173b-4021-a69f-xxxxxxxxxxxx",
  "model": "doubao-seedance-2-5-betydance"
}

响应字段说明

字段	类型	说明
`output.task_id`	string	任务 ID，用于查询任务状态
`output.task_status`	string	任务状态：`PENDING`（排队中）
`request_id`	string	请求唯一标识
`model`	string	使用的模型名称

错误响应

{
  "error": {
    "message": "错误描述",
    "type": "错误类型"
  }
}

常见错误类型：

authentication_error：API Key 无效或缺失
invalid_request_error：请求参数错误
not_found：模型不存在或无权限
upstream_error：上游服务错误

2. 查询视频生成任务

GET /contents/generations/tasks/{task_id}

完整路径：https://api.alimxj.com/v3/contents/generations/tasks/{task_id}

查询已创建的视频生成任务状态和结果。

路径参数

参数	类型	必填	说明
`task_id`	string	是	任务 ID（创建任务时返回的 `output.task_id` 字段）

请求示例

curl -X GET "https://api.alimxj.com/v3/contents/generations/tasks/task_91b0550251e547948f36287e" \
  -H "Authorization: Bearer YOUR_API_KEY"

任务处理中响应

{
  "id": "a72f41c9-12b3-4e5f-8d9c-xxxxxxxxxxxx",
  "task_id": "a72f41c9-12b3-4e5f-8d9c-xxxxxxxxxxxx",
  "model": "doubao-seedance-2-5-betydance",
  "status": "running",
  "created_at": 1782891873,
  "updated_at": 1782891873
}

任务成功响应

{
  "id": "a72f41c9-12b3-4e5f-8d9c-xxxxxxxxxxxx",
  "task_id": "a72f41c9-12b3-4e5f-8d9c-xxxxxxxxxxxx",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-2-5/xxxxxxxx.mp4?X-Tos-Algorithm=..."
  },
  "model": "doubao-seedance-2-5-betydance",
  "ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "usage": {
    "total_tokens": 108900,
    "completion_tokens": 108900
  },
  "created_at": 1782891873,
  "updated_at": 1782892090
}

响应字段说明

字段	类型	说明
`id`	string	任务 ID
`task_id`	string	同 `id`
`status`	string	任务状态：`running`（处理中）/ `succeeded`（成功）/ `failed`（失败）
`content.video_url`	string	视频下载 URL（仅 `succeeded` 时返回，24h 有效）
`model`	string	模型名称
`ratio`	string	视频宽高比
`resolution`	string	分辨率，如 `720p`、`1080p`
`duration`	integer	视频时长（秒）
`seed`	integer	生成种子（可用于复现相同结果）
`framespersecond`	integer	帧率（fps）
`execution_expires_after`	integer	结果过期时间（秒），默认 172800（48h）
`created_at`	integer	创建时间（Unix 时间戳）
`updated_at`	integer	更新时间（Unix 时间戳）
`usage.total_tokens`	integer	总 Token 消耗
`usage.completion_tokens`	integer	生成 Token 数
`usage.SR`	integer	分辨率档位（720 / 1080）
`usage.duration`	integer	视频时长（秒）
`usage.ratio`	string	宽高比

🔐 HMAC-SHA256 签名认证

认证流程

客户端使用 SecretAccessKey 对请求进行签名
服务端使用相同的 SecretAccessKey 验证签名
签名包含时间戳，防止重放攻击（有效期 5 分钟）

必需参数

参数	说明	示例
`AccessKeyId`	访问密钥 ID（即 API Key）	`tk-bb94a758...`
`SecretAccessKey`	访问密钥 Secret	`sk_xxx...`
`Region`	区域（固定值）	`cn-beijing`
`Service`	服务名（固定值）	`volcengine`

签名步骤

步骤 1：构建 CanonicalRequest

HTTPMethod
CanonicalURI
CanonicalQueryString
CanonicalHeaders
SignedHeaders
HashedPayload

示例：

POST
/v3/contents/generations/tasks

content-type:application/json
host:api.alimxj.com
x-date:20260821T081000Z

content-type;host;x-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

说明：

HTTPMethod：HTTP 方法（POST/GET）
CanonicalURI：请求路径（如 /v3/contents/generations/tasks）
CanonicalQueryString：URL 查询参数（按名称排序，无参数则为空）
CanonicalHeaders：参与签名的 HTTP 头（按名称排序，每个头占一行）
SignedHeaders：参与签名的头列表（分号分隔，小写）
HashedPayload：请求体的 SHA256 哈希（hex 格式）

步骤 2：构建 StringToSign

HMAC-SHA256
{X-Date}
{CredentialScope}
{HashedCanonicalRequest}

示例：

HMAC-SHA256
20260821T081000Z
20260821/cn-beijing/volcengine/request
a098d2841e0452ec987a2b017a305befed481d39ea335810b8a8455be9e4cb2f

说明：

X-Date：UTC 时间，格式 YYYYMMDDTHHMMSSZ
CredentialScope：{Date}/{Region}/{Service}/request
HashedCanonicalRequest：CanonicalRequest 的 SHA256 哈希

步骤 3：密钥派生

k_date = HMAC-SHA256(SecretAccessKey, Date)
k_region = HMAC-SHA256(k_date, Region)
k_service = HMAC-SHA256(k_region, Service)
k_signing = HMAC-SHA256(k_service, "request")

步骤 4：计算签名

signature = HMAC-SHA256(k_signing, StringToSign)

步骤 5：构建 Authorization 头

HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

⚠️ Host Header 注意事项

签名时 Host 必须与服务端实际看到的 Host 一致。本服务对外 Host 为：

场景	Host 值
梦想家接入	`api.alimxj.com`（不带端口）
本地测试	`127.0.0.1`

Python 完整示例

import hmac
import hashlib
import requests
import json
from datetime import datetime, timezone
from urllib.parse import urlparse

class VolcengineSigner:
    """火山引擎签名器"""

    def __init__(self, access_key_id, secret_access_key, region='cn-beijing', service='volcengine'):
        self.access_key_id = access_key_id
        self.secret_access_key = secret_access_key
        self.region = region
        self.service = service

    def sign_request(self, method, url, headers, body=''):
        parsed = urlparse(url)
        host = parsed.netloc
        path = parsed.path or '/'
        query_string = parsed.query

        now = datetime.now(timezone.utc)
        x_date = now.strftime('%Y%m%dT%H%M%SZ')
        short_date = now.strftime('%Y%m%d')

        headers_to_sign = {
            'host': host,
            'content-type': headers.get('Content-Type', 'application/json'),
            'x-date': x_date
        }
        signed_headers_list = sorted(headers_to_sign.keys())
        signed_headers = ';'.join(signed_headers_list)

        canonical_headers = ''
        for key in signed_headers_list:
            canonical_headers += f"{key}:{headers_to_sign[key].strip()}\n"

        body_hash = hashlib.sha256(body.encode('utf-8')).hexdigest()

        canonical_request = (
            f"{method}\n"
            f"{path}\n"
            f"{query_string}\n"
            f"{canonical_headers}\n"
            f"{signed_headers}\n"
            f"{body_hash}"
        )

        credential_scope = f"{short_date}/{self.region}/{self.service}/request"
        string_to_sign = (
            f"HMAC-SHA256\n"
            f"{x_date}\n"
            f"{credential_scope}\n"
            f"{hashlib.sha256(canonical_request.encode('utf-8')).hexdigest()}"
        )

        k_date = hmac.new(self.secret_access_key.encode(), short_date.encode(), hashlib.sha256).digest()
        k_region = hmac.new(k_date, self.region.encode(), hashlib.sha256).digest()
        k_service = hmac.new(k_region, self.service.encode(), hashlib.sha256).digest()
        k_signing = hmac.new(k_service, b"request", hashlib.sha256).digest()
        signature = hmac.new(k_signing, string_to_sign.encode('utf-8'), hashlib.sha256).hexdigest()

        authorization = (
            f"HMAC-SHA256 "
            f"Credential={self.access_key_id}/{credential_scope}, "
            f"SignedHeaders={signed_headers}, "
            f"Signature={signature}"
        )

        result_headers = headers.copy()
        result_headers['X-Date'] = x_date
        result_headers['Authorization'] = authorization
        return result_headers


# 使用示例
if __name__ == "__main__":
    ACCESS_KEY_ID = "YOUR_API_KEY"
    SECRET_ACCESS_KEY = "YOUR_SECRET_KEY"
    BASE_URL = "https://api.alimxj.com"

    signer = VolcengineSigner(ACCESS_KEY_ID, SECRET_ACCESS_KEY)

    url = f"{BASE_URL}/v3/contents/generations/tasks"
    headers = {'Content-Type': 'application/json'}
    data = {
        "model": "doubao-seedance-2-5-betydance",
        "content": [{"type": "text", "text": "一只小猫在草地上追蝴蝶"}],
        "ratio": "16:9",
        "duration": 5
    }
    body = json.dumps(data, ensure_ascii=False)

    signed_headers = signer.sign_request('POST', url, headers, body)
    response = requests.post(url, headers=signed_headers, data=body.encode('utf-8'))
    print(f"状态码: {response.status_code}")
    print(f"响应: {json.dumps(response.json(), ensure_ascii=False, indent=2)}")

签名错误排查

错误	可能原因	解决方案
`Signature verification failed`	Host 不匹配	确保签名的 Host 与服务端一致
`Signature verification failed`	时间戳过期	检查系统时间，确保在 5 分钟内
`Invalid Authorization header`	格式错误	检查 Authorization 头格式
`Invalid AccessKeyId`	API Key 错误	检查 AccessKeyId 是否正确

📦 资产管理接口

资产管理接口用于管理视频生成所需的参考素材（图片、视频、音频）。通过 asset:// 协议可在视频生成任务中引用已上传的素材。

接口入口

POST /api/asset?Action=<Action>&Version=2024-01-01

完整路径：https://api.alimxj.com/v1/api/asset?Action=<Action>&Version=2024-01-01

Action 决定具体接口，Version 固定 2024-01-01
全部使用 POST 方法，Content-Type: application/json
鉴权：Authorization: Bearer <your-api-key>

Action 列表

Action	说明	章节
`CreateAssetGroup`	创建素材组	素材组管理
`ListAssetGroups`	列出素材组	素材组管理
`GetAssetGroup`	查询单个素材组	素材组管理
`UpdateAssetGroup`	更新素材组	素材组管理
`DeleteAssetGroup`	删除素材组	素材组管理
`CreateAsset`	创建素材	素材管理
`ListAssets`	列出素材	素材管理
`GetAsset`	查询单个素材	素材管理
`UpdateAsset`	更新素材	素材管理
`DeleteAsset`	删除素材	素材管理
`CreateVisualValidateSession`	创建视觉校验会话（真人认证）	视觉校验
`GetVisualValidateResult`	查询视觉校验结果	视觉校验

素材组管理

CreateAssetGroup — 创建素材组

请求字段	类型	必填	说明
`Name`	string	是	组名（同 key 下唯一）
`Description`	string	否	组描述
`GroupType`	string	否	组类型，仅支持 `AIGC`（默认）

curl -X POST "https://api.alimxj.com/v1/api/asset?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"Name":"测试组","Description":"用于视频参考的图片","GroupType":"AIGC"}'

ListAssetGroups — 列出素材组

请求字段	类型	必填	说明
`Filter.Name`	string	否	按组名过滤（模糊匹配）
`PageNumber`	int	否	页码，默认 1
`PageSize`	int	否	每页条数，默认 10

GetAssetGroup — 查询单个素材组

请求字段	类型	必填	说明
`Id`	string	是	组 Id

UpdateAssetGroup — 更新素材组

请求字段	类型	必填	说明
`Id`	string	是	组 Id
`Name`	string	否	新组名
`Description`	string	否	新描述

curl -X POST "https://api.alimxj.com/v1/api/asset?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer *** \
  -d '{"Id":"187507198107058200","Name":"新名字","Description":"新描述"}'

DeleteAssetGroup — 删除素材组

请求字段	类型	必填	说明
`Id`	string	是	组 Id

素材管理

CreateAsset — 创建素材

请求字段	类型	必填	说明
`Name`	string	是	素材名
`GroupId`	string	是	所属组 Id
`URL`	string	是	素材资源 URL
`AssetType`	string	是	`Image` / `Video` / `Audio`

异步就绪：素材创建后 Status 初始为 Processing，就绪后变 Active。仅 Active 素材可用于视频 asset:// 引用。

ListAssets — 列出素材

请求字段	类型	必填	说明
`Filter.GroupIds`	string[]	否	按组 Id 列表过滤
`PageNumber`	int	否	页码，默认 1
`PageSize`	int	否	每页条数，默认 10

GetAsset — 查询单个素材

请求字段	类型	必填	说明
`Id`	string	是	素材 Id

UpdateAsset — 更新素材

请求字段	类型	必填	说明
`Id`	string	是	素材 Id
`Name`	string	否	新素材名

curl -X POST "https://api.alimxj.com/v1/api/asset?Action=UpdateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer *** \
  -d '{"Id":"182533555060998168","Name":"新名字"}'

DeleteAsset — 删除素材

请求字段	类型	必填	说明
`Id`	string	是	素材 Id

视频生成中的 asset:// 引用

视频生成接口的 content 数组里，可用 asset://<Id> 引用已创建的素材替代公网 URL。

引用写法

// 图片引用
{"type":"image_url","role":"reference_image","image_url":{"url":"asset://<AssetId>"}}

// 视频引用
{"type":"video_url","role":"reference_video","video_url":{"url":"asset://<AssetId>"}}

// 音频引用
{"type":"audio_url","role":"reference_audio","audio_url":{"url":"asset://<AssetId>"}}

归属校验

场景	结果
引用自己 key 下的 Active 素材	200 放行
引用他人 key 下的素材	403 `asset not owned by key`
无 asset:// 引用（纯文生视频）	200 不校验

私有隔离：所有查询/更新/删除操作带 key 归属过滤，只能操作自己 key 下的组与素材。

🔍 视觉校验（真人认证）

视觉校验用于真人活体认证。调用 CreateVisualValidateSession 创建认证会话，上游返回 BytedToken；用户在 H5 页面完成认证后，调用 GetVisualValidateResult 查询结果，认证成功后自动回填 GroupId 并将组转为 active。

CreateVisualValidateSession — 创建视觉校验会话

请求字段	类型	必填	说明
`CallbackURL`	string	是	认证结果回调 URL

curl -X POST "https://api.alimxj.com/v1/api/asset?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer *** \
  -d '{"CallbackURL":"https://example.com/callback"}'

响应示例：

{
  "ResponseMetadata": {
    "Action": "CreateVisualValidateSession",
    "Region": "cn-beijing",
    "RequestId": "20260811151901191F12565842363DCE4D",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "BytedToken": "202608111519011904A1CECB71B3B798C0",
    "CallbackURL": "https://example.com/callback",
    "H5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=<token>&uid=<uid>"
  }
}

字段说明：

BytedToken：认证会话令牌，用于查询结果
H5Link：用户在浏览器中打开此链接完成真人认证
CallbackURL：认证完成后回调通知地址

GetVisualValidateResult — 查询视觉校验结果

请求字段	类型	必填	说明
`BytedToken`	string	是	创建会话时返回的 `BytedToken`

curl -X POST "https://api.alimxj.com/v1/api/asset?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer *** \
  -d '{"BytedToken":"202608111519011904A1CECB71B3B798C0"}'

响应示例（认证成功）：

{
  "ResponseMetadata": {
    "Action": "GetVisualValidateResult",
    "Region": "cn-beijing",
    "RequestId": "2026081116104914FE6115A8A9CFD08C2C2C",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": {
    "GroupId": "group-20260811161038-fdjdf"
  }
}

字段说明：

GroupId：认证成功后返回的真人素材组 ID（GroupType=LivenessFace），可用于视频生成中的 asset:// 引用

与 AIGC 组的区别：真人组（LivenessFace）不能通过 CreateAssetGroup 创建，只能通过 CreateVisualValidateSession 创建；其生命周期由认证状态驱动（pending → active / failed）。

📋 任务管理

查询任务列表

GET /contents/generations/tasks

完整路径：https://api.alimxj.com/v3/contents/generations/tasks

查询当前 API Key 下的所有视频生成任务。

参数	类型	必填	说明
`page_num`	integer	否	页码，默认 1
`page_size`	integer	否	每页条数，默认 10，最大 100
`filter.status`	string	否	按状态过滤：`running` / `succeeded` / `failed`
`filter.model`	string	否	按模型名称过滤

curl -X GET "https://api.alimxj.com/v3/contents/generations/tasks?page_num=1&page_size=5&filter.status=succeeded" \
  -H "Authorization: Bearer ***

响应示例：

{
  "items": [
    {
      "id": "task_039143e03c974564bfed4d07",
      "model": "doubao-seedance-2-5-betydance",
      "status": "succeeded",
      "content": {
        "video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/..."
      },
      "ratio": "16:9",
      "resolution": "720p",
      "duration": 5,
      "usage": {
        "total_tokens": 108000,
        "completion_tokens": 108000
      },
      "created_at": 1788395939,
      "updated_at": 1788395939
    }
  ],
  "page_num": 1,
  "page_size": 5,
  "total": 10
}

取消/删除任务

DELETE /contents/generations/tasks/{task_id}

完整路径：https://api.alimxj.com/v3/contents/generations/tasks/{task_id}

取消正在处理的任务或删除已完成的任务记录。

参数	类型	必填	说明
`task_id`	string	是	任务 ID（路径参数）

行为说明：

running 状态：取消任务（停止生成）
succeeded / failed 状态：删除任务记录
queued 状态：取消排队中的任务

curl -X DELETE "https://api.alimxj.com/v3/contents/generations/tasks/task_039143e03c974564bfed4d07" \
  -H "Authorization: Bearer ***

成功响应：返回空对象 {}

📝 注意事项

任务有效期：任务 ID 有效期为 24 小时，请及时查询结果
视频下载链接：成功响应中的 video_url 有效期为 24 小时，请及时下载
轮询间隔：建议 5–15 秒轮询一次任务状态，避免过于频繁
素材引用规则：在 type: "text" 中，按 content 数组顺序从 1 开始编号，使用 图片N / 视频N / 音频N 引用对应素材（如 图片1、视频1、音频1，不带方括号，中文写法，Seedance 仅识别此格式）
素材 URL 有效期：GetAsset / ListAssets 返回的 URL 由上游签发，约 12 小时失效，需及时使用
素材就绪才可引用：仅 Status=Active 的素材可用于视频 asset:// 引用；创建后通常需轮询 5–30 秒等待 Processing → Active
跨 key 引用禁止：asset:// 引用他人 key 下的素材会被 fail-closed 拦截返回 403
私有隔离：素材组/素材的查询、更新、删除均带 key 归属过滤，越权访问与资源不存在统一返回 404
并发限制：单个 API Key 的并发任务数有限制，具体请咨询客服
内容审核：生成的视频会经过内容安全审核，违规内容将被拦截
计费方式：按生成视频的分辨率和时长计费，详见定价页面