API 文档
概览
TokenSea 提供统一的 AI 模型网关,接入全系列国产主流大模型。一次接入,访问多个供应商,通过单一控制面板管理密钥、配额和路由。
Base URL
https://agent.tokensea.ai/v1
认证方式
Authorization: Bearer <your_tokensea_key>
接口概览
| 接口 | 方法 | 地址 | 说明 |
|---|---|---|---|
| 对话补全 | POST | /v1/chat/completions | 核心对话接口,支持流式、Tool Calling、多模态 |
| 创建视频任务 | POST | /v1/video/generations | 提交视频生成任务,返回任务 ID |
| 查询视频任务 | GET | /v1/video/generations/{task_id} | 查询任务状态和结果 |
| Seedance 原生接口 | POST / GET | /v3/contents/generations/tasks | 创建任务;查询时在路径末尾追加任务 ID |
| 模型列表 | GET | /v1/models | 获取可用模型完整列表 |
快速开始
三步上手:注册账户 → 获取 API Key → 发起请求。兼容 OpenAI 格式,可直接使用现有客户端库。
1. 安装 OpenAI SDK
# Python
pip install openai
# Node.js
npm install openai
2. 设置 API Key
# macOS / Linux
export API_KEY="your_tokensea_key"
# Windows PowerShell
$env:API_KEY="your_tokensea_key"
3. 发起第一次请求
from openai import OpenAI
import os
client = OpenAI(
base_url="https://agent.tokensea.ai/v1",
api_key=os.environ["API_KEY"]
)
response = client.chat.completions.create(
model="glm-5",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "你好,请介绍一下 TokenSea"}
],
max_completion_tokens=1024,
temperature=0.7
)
print(response.choices[0].message.content)
cURL 示例
curl -sS "https://agent.tokensea.ai/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5",
"messages": [{"role": "user", "content": "你好"}],
"max_completion_tokens": 256
}'
流式响应
for chunk in client.chat.completions.create(
model="glm-5",
messages=[{"role": "user", "content": "给我讲个故事"}],
stream=True
):
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
[DONE] 信号之前,会有一条 choices 为空数组的 usage 统计 chunk。客户端处理流式数据时,需跳过 choices 为空的 chunk,否则会触发数组越界错误。API Keys
从 TokenSea 控制台 创建和管理 API Key。请始终将密钥存储在环境变量中,切勿提交到代码仓库。
- API Key 必须在 agent.tokensea.ai 控制台创建
messages参数为必填,不能省略- 接口路径固定为
/v1/chat/completions
LLM 对话接口
适用于 MiniMax-M2.5、deepseek-v3.2、glm-5、glm-5.1、kimi-k2.5、qwen3.6-plus 等国产核心模型。
请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model | string | 是 | — | 模型 ID |
messages | array | 是 | — | 对话消息列表 |
stream | boolean | 否 | false | 是否流式返回 |
max_completion_tokens | integer | 否 | 1024 | 最大生成 Token 数 |
temperature | float | 否 | 0.7 | 采样温度(0-2) |
response_format | object | 否 | {"type":"text"} | 设为 {"type":"json_object"} 启用 JSON 模式 |
tools | array | 否 | — | 工具定义列表 |
tool_choice | string | 否 | auto | auto / none / required |
响应字段
| 字段 | 说明 |
|---|---|
choices[0].message.content | 回复文本(最终回答) |
choices[0].message.reasoning_content | 思维链推理过程(仅 glm-5/5.1/qwen3.6-plus) |
choices[0].message.tool_calls | 工具调用列表(Tool Calling 时) |
usage.prompt_tokens | 输入 Token 数 |
usage.completion_tokens | 输出 Token 数 |
JSON Mode 示例
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[{"role": "user", "content": "列出3个AI应用场景"}],
response_format={"type": "json_object"}
)
Tool Calling 示例
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}]
response = client.chat.completions.create(
model="kimi-k2.5",
messages=[{"role": "user", "content": "北京天气怎么样?"}],
tools=tools, tool_choice="auto"
)
tool_call_id 格式不同,回传时必须原样使用模型返回的值。图片理解(仅 kimi-k2.5)
response = client.chat.completions.create(
model="kimi-k2.5",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图片"},
{"type": "image_url", "image_url": {"url": "https://example.com/img.jpg"}}
]
}]
)
Seedance 视频生成
通过 TokenSea 调用 Seedance,完成文生视频、首尾帧生成和多模态参考生成。视频生成是异步任务:提交后保存任务 ID,再查询同一个任务,成功后下载视频。
content 结构,可明确指定参考素材的角色。已有 /v1/video/generations 客户端仍可使用兼容接口,两种接口的请求和响应结构不同。地址与认证
以下路径从域名根开始拼接,不要在 /v1 后追加 /v3。视频和本页素材管理接口均使用你的 TokenSea API Key。
| 操作 | 方法 | 路径 |
|---|---|---|
| 创建任务 | POST | /v3/contents/generations/tasks |
| 查询任务 | GET | /v3/contents/generations/tasks/{task_id} |
| 素材管理 | POST | /volcengine/assets/?Action={action}&Version=2024-01-01 |
| 可用模型 | GET | /v1/models |
/api/v3/contents/generations/tasks 也支持相同的创建、查询操作。本文统一使用 /v3。
export TOKENSEA_API_KEY="替换为你的 TokenSea API Key"
Seedance 模型名称
目前支持以下 4 个模型。请求时将完整模型 ID 填入 model,保留前缀、日期和标点。
| 模型 ID | 名称 |
|---|---|
byteplus/dreamina-seedance-2-0-260128 | Seedance 2.0 |
byteplus/dreamina-seedance-2-0-fast-260128 | Seedance 2.0 Fast |
byteplus/dreamina-seedance-2-0-mini-260615 | Seedance 2.0 Mini |
byteplus/dreamina-seedance-2-5-260628 | Seedance 2.5 |
本文示例使用 byteplus/dreamina-seedance-2-0-260128。不同模型支持的分辨率、时长和输入组合可能不同,请按所选模型的要求设置参数。
GET /v1/models 的结果及控制台权限为准。查询你的 API Key 可用模型
示例模型为 byteplus/dreamina-seedance-2-0-260128。请先在控制台或模型列表中确认账号可用的完整模型 ID;不同版本、分辨率、时长及输入组合的支持范围可能不同。
curl --fail-with-body -sS "https://agent.tokensea.ai/v1/models" \
-H "Authorization: Bearer $TOKENSEA_API_KEY"
Seedance 相关接口清单
下表覆盖视频创建、查询、下载及素材管理。选择一种创建与查询协议配套使用;V3 与 /v1 兼容接口的请求和响应格式不同。
| 方法 | 路径 | 用途 / 说明 |
|---|---|---|
| POST | /v3/contents/generations/tasks | V3 创建视频任务,使用本页原生 content 示例。 |
| GET | /v3/contents/generations/tasks/{task_id} | V3 查询任务;成功结果为 content.video_url。 |
| POST | /api/v3/contents/generations/tasks | V3 创建任务的兼容别名。 |
| GET | /api/v3/contents/generations/tasks/{task_id} | V3 查询任务的兼容别名。 |
| POST | /v1/video/generations | 既有视频生成接口,按对应模型的兼容格式提交。 |
| GET | /v1/video/generations/{task_id} | 查询既有视频任务。 |
| POST | /v1/videos | OpenAI 风格的视频创建入口。 |
| GET | /v1/videos/{task_id} | OpenAI 风格的视频查询入口。 |
| GET | /v1/videos/{task_id}/content | 下载已完成任务的视频内容,需认证。 |
| GET | /v1/asset-projects | 旧客户端的项目发现兼容接口。 |
| POST | /volcengine/assets/?Action={action}&Version=2024-01-01 | 素材与素材组操作,完整 Action 清单见下文。 |
| GET | /v1/models | 查询当前 API Key 可用的模型。 |
目前不提供 Seedance 任务列表、删除、取消或 Remix 功能。需要复用画面时,请使用模型支持的参考图片或参考视频输入。
通过任务 ID 下载视频
任务成功后,使用完整任务 ID 和创建时相同的 API Key,通过以下接口下载。启用视频托管时,查询返回的 content.video_url 也是需要认证的网关地址,不能当作免认证直链。请在视频可下载期限内完成保存。
curl --fail --location "https://agent.tokensea.ai/v1/videos/$TASK_ID/content" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
--output seedance-result.mp4
创建与幂等重试
创建视频任务、CreateAssetGroup 和 CreateAsset 支持可选请求头 Idempotency-Key。建议从第一次提交就携带:每个新操作使用独立的唯一标识,重试原操作时保持原值。标识不能为空白,长度最多 200 字节;可使用 UUID 或唯一业务请求号。
下文创建示例中的 replace-with-unique-…-key 均为占位值,首次执行前请替换并保存。重试须使用相同的 TokenSea API Key、接口路径、查询串和原始请求体;JSON 空格、字段顺序或查询参数顺序变化也可能触发冲突。不要在重试时切换 /v3 与 /api/v3,或改用其他 Key、路径或新的幂等键,这些请求不能复用原记录。
| 情况 | 返回与处理 |
|---|---|
| 同一键、相同请求,已有保存的响应 | 重放原 HTTP 状态和响应体,并返回 Idempotency-Replayed: true。原响应可能是成功,也可能是错误;不会再次创建。 |
| 同一键、相同请求,仍在处理或结果未确认 | 可能返回 409。保留原键和资源 ID;稍后重试原请求或联系支持,不要换键重新创建。 |
| 同一键、相同路径和操作,但请求内容不同 | 返回 409。核对原请求;真正的新操作应使用新键,原操作结果不明时先核对。 |
| 首次失败且服务端确认尚未创建资源或向上游提交 | 允许使用原键重试。不能仅凭 HTTP 错误码判断请求是否已经提交。 |
未携带此请求头的创建请求没有上述去重保护。创建超时或断连时,先保留原请求信息;已使用幂等键的请求可按上述规则退避重试。若明确提示提交未确认,请按下一节核对。以下创建示例用 --dump-header - 显示响应头,便于保留请求 ID 和素材 ID。
文生视频:提交第一个任务
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-text-video-key" \
-d '{
"model": "byteplus/dreamina-seedance-2-0-260128",
"content": [
{"type": "text", "text": "一只猫在雪地里奔跑,镜头缓慢跟随,电影质感"}
],
"duration": 5,
"ratio": "16:9",
"resolution": "720p",
"watermark": false
}'
创建响应示意(以实际返回值为准):
{"id": "task_example"}
完整保存 id。任务 ID 可能以 task_ 或 cgt- 等形式返回;不要截断、替换前缀或自行拼接。返回 ID 只表示任务已提交,不表示视频生成成功。
常用参数
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 账号已开通的完整模型 ID。 |
content | array | 文本与参考媒体。文本使用 {"type":"text","text":"…"}。 |
duration | integer | 视频时长,单位秒;示例为 5,允许范围取决于模型。 |
ratio | string | 例如 16:9、9:16 或 adaptive,需与模型及任务类型匹配。 |
resolution | string | 例如 720p;支持的分辨率取决于模型。 |
generate_audio | boolean | 是否生成音频;仅用于支持此能力的模型。 |
watermark | boolean | 水印开关;显式关闭请传 false。 |
seed | integer | 随机种子;按模型支持范围设置,允许时可显式传 0。 |
auto_create_assets | boolean | 是否自动将 HTTP(S) 参考图片转为临时素材,详见下文。 |
提交未确认与费用
创建请求发送后发生超时、断连或异常响应时,上游仍可能已经受理。提交未确认表示需要核对受理结果,不能据此判断“没有创建成功”。请勿为同一次操作重新创建任务或素材,保留原幂等键、请求与响应信息并联系支持。
| 场景 | 识别方式 | 处理方式 |
|---|---|---|
| 素材创建结果未确认 | 后续 GetAsset 可能返回 Result.Status=Failed、Result.Error.Code=SubmissionUnconfirmed。 | 保留创建响应头中的 X-Seedance-Asset-Id(若有),用该 ID 查询并联系支持核对,不要重新创建。 |
| 视频提交结果未确认 | V3 创建错误中的 error.data.submission_status=unconfirmed;error.code 可能是 do_request_failed、上游错误码或 submission_unconfirmed,不能只匹配一种错误码。 | 保存 error.data.task_id。查询若返回 failed 且 error.message=submission_unconfirmed,同样需要核对。 |
| 上游已受理,但任务记录保存失败 | V3 创建错误中的 error.code=task_persistence_failed。 | 保存返回的任务 ID,以及 error.data.recovery_token(若有),通过支持渠道核对恢复,不要重新提交。 |
V3 提交未确认响应示意(错误码和 HTTP 状态以实际返回为准):
{
"error": {
"code": "do_request_failed",
"message": "upstream request timed out",
"data": {
"task_id": "task_example",
"submission_status": "unconfirmed"
}
}
}
failed 或 HTTP 5xx 本身不代表已退款。请保留任务 ID 联系支持,确认受理结果和费用;若响应中没有资源 ID,也请保留幂等键、请求时间和请求 ID,避免重复创建产生费用。首尾帧与多模态参考
将媒体放入 content,并通过 role 指定用途。下表表示字段结构,不代表每个模型都支持任意组合。
| 用途 | type | 媒体字段 | role |
|---|---|---|---|
| 首帧 | image_url | image_url.url | first_frame |
| 尾帧(与首帧配合) | image_url | image_url.url | last_frame |
| 参考图片 | image_url | image_url.url | reference_image |
| 参考视频 | video_url | video_url.url | reference_video |
| 参考音频 | audio_url | audio_url.url | reference_audio |
首帧生成示例
将 https://example.com/first-frame.jpg 替换为可公开访问的图片直链。示例域名仅为占位,不提供测试素材。
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-first-frame-key" \
-d '{
"model": "byteplus/dreamina-seedance-2-0-260128",
"content": [
{"type": "text", "text": "人物缓缓回头,保持面部和服装一致,镜头平稳推进"},
{"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
],
"duration": 5,
"ratio": "adaptive",
"resolution": "720p",
"auto_create_assets": true
}'
首帧 + 尾帧
将上例的 content 替换为以下数组,作为新任务提交时使用新的 Idempotency-Key,其他参数按模型要求设置。使用 Seedance 2.5 首帧或首尾帧任务时,ratio 应设为 adaptive。
[
{"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"}
]
多参考输入
以下为 content 数组结构示例。修改输入后作为新任务提交时,使用新的 Idempotency-Key。图片、视频、音频的数量、大小、时长及组合限制,以所选模型的实际能力为准;音频参考是否需要配合图片或视频也取决于模型。
[
{"type": "text", "text": "参考图片中的主体、视频中的镜头运动与音频节奏,生成一段短片"},
{"type": "image_url", "image_url": {"url": "https://example.com/reference.jpg"}, "role": "reference_image"},
{"type": "video_url", "video_url": {"url": "https://example.com/motion.mp4"}, "role": "reference_video"},
{"type": "audio_url", "audio_url": {"url": "https://example.com/rhythm.mp3"}, "role": "reference_audio"}
]
查询任务与下载结果
使用创建时相同的 API Key 和完整任务 ID 查询。建议从 5 秒间隔开始轮询,并设置业务等待上限;超时后保留 ID,稍后继续查询。
若创建响应已提示提交未确认,请先联系支持核对。查询返回 failed 时需检查错误内容,不能仅凭任务状态判断受理结果或退款情况。
TASK_ID="替换为创建响应中的完整 id"
curl --fail-with-body -sS "https://agent.tokensea.ai/v3/contents/generations/tasks/$TASK_ID" \
-H "Authorization: Bearer $TOKENSEA_API_KEY"
| 状态 | 含义 | 处理方式 |
|---|---|---|
queued | 等待处理 | 继续查询同一个任务。 |
running | 正在处理 | 继续等待;处理时长随负载和输入变化。 |
creating_assets / processing / pending | 部分响应中的处理中状态 | 同样继续查询,不要重复创建任务。 |
succeeded | 生成成功 | 读取 content.video_url 并下载。 |
failed / cancelled / expired | 失败、取消或过期 | 结束轮询,检查 error.code 和 error.message。 |
成功响应示意,仅展示关键字段:
{
"id": "task_example",
"status": "succeeded",
"content": {"video_url": "https://example.com/generated.mp4"}
}
Python 轮询示例
安装 requests,并设置 TOKENSEA_API_KEY 与 TASK_ID 环境变量。此示例只查询已创建任务;遇到网络波动、429 或 5xx 时退避重试,达到 20 分钟上限后保留原任务 ID。
import os
import time
import requests
key = os.environ["TOKENSEA_API_KEY"]
task_id = os.environ["TASK_ID"] # 终端中使用 export TASK_ID="实际 id"
url = f"https://agent.tokensea.ai/v3/contents/generations/tasks/{task_id}"
headers = {"Authorization": f"Bearer {key}"}
deadline = time.monotonic() + 20 * 60
wait = 5
while time.monotonic() < deadline:
try:
response = requests.get(url, headers=headers, timeout=30)
except (requests.Timeout, requests.ConnectionError):
time.sleep(wait)
wait = min(wait * 2, 30)
continue
if response.status_code == 429 or response.status_code >= 500:
time.sleep(wait)
wait = min(wait * 2, 30)
continue
response.raise_for_status()
task = response.json()
status = task.get("status")
error = task.get("error") or {}
if (error.get("code") == "submission_unconfirmed"
or error.get("message") == "submission_unconfirmed"):
raise RuntimeError(
f"提交未确认,预扣额度可能保留。请保留任务 ID {task_id} 联系支持,不要重新创建:{error}"
)
if status == "succeeded":
video_url = (task.get("content") or {}).get("video_url")
if not video_url:
raise RuntimeError(f"任务成功但缺少视频地址,请保留任务 ID:{task_id}")
print(video_url)
break
if status in {"failed", "cancelled", "expired"}:
raise RuntimeError(f"任务 {task_id} 结束:{task.get('error', task)}")
if status not in {"queued", "running", "pending", "processing", "creating_assets"}:
raise RuntimeError(f"未知任务状态,请保留任务 ID 并检查响应:{task}")
wait = 5
time.sleep(wait)
else:
raise TimeoutError(f"等待超时,不代表任务失败。稍后继续查询:{task_id}")
保存视频
确认查询返回 status=succeeded 后,使用完整任务 ID 和 API Key 下载。以下方式同时适用于托管视频和普通视频结果;不要直接使用无认证的下载命令访问 content.video_url。
TASK_ID="替换为创建响应中的完整 id"
curl --fail --location "https://agent.tokensea.ai/v1/videos/$TASK_ID/content" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
--output seedance-result.mp4
请及时保存并确认文件能正常播放。启用视频托管时,查询响应中的 delivery.expires_at(若有,Unix 秒级时间戳)表示视频交付的到期时间;接口地址保持相同也不代表视频会永久保留。
自动创建临时素材
仅本次任务使用的参考图片,可以直接传 HTTP(S) URL 并设置 auto_create_assets: true。需要多次复用的素材,请使用下一节的素材管理接口。
| 传值 | 行为 |
|---|---|
true | 将 HTTP(S) 参考图片自动创建为临时素材后用于生成;已有 asset:// 引用保持复用。 |
false | 不自动转换图片 URL;能否直接使用 URL 取决于模型能力。已有素材仍可通过 asset:// 使用。 |
| 不传 | 使用服务默认值。建议显式传入 true 或 false,明确本次请求的行为。 |
此选项仅适用于参考图片,不改变模型支持的输入组合。临时素材仅供本次任务使用,无需手动删除;需要多次复用时,请使用素材管理接口。建议显式传入布尔值 true 或 false,字符串 "true" 不被接受;当前接口接受 null 并按关闭处理,不等同于省略参数使用默认值。
可复用素材管理
适用于需要重复引用的图片、视频和音频,实际可用类型取决于所选模型和服务能力。完整流程:创建素材组 → 创建素材 → 查询至 Active → 使用 asset:// 生成视频 → 不再需要时删除。
创建素材组和素材时,同样遵循幂等重试规则,每个创建操作分别使用唯一键。AssetType 支持 Image、Video、Audio,区分大小写。
| AssetType | 媒体字段与引用示例 | 参考角色 |
|---|---|---|
Image | image_url.url: asset://tsa_image_example | reference_image;首尾帧可用 first_frame / last_frame |
Video | video_url.url: asset://tsa_video_example | reference_video |
Audio | audio_url.url: asset://tsa_audio_example | reference_audio |
引用字段应与创建时的素材类型对应,role 放在媒体内容项上,与 type 同级。以上只说明引用结构,支持的角色和输入组合仍以具体模型为准。
素材可复用期限与下载链接有效期
可复用素材不代表永久保存。素材及素材组可能按服务配置自动清理;开启素材自动清理时,会结合保留期限和最近成功提交引用任务的时间判断,查询或下载不等于续期。具体保留期限以服务实际配置为准。
GetAsset / ListAssets 可能返回素材源文件的 URL 和 URLExpiresAt(UTC 日期时间)。该 URL 的签名有效期与素材可复用期限独立:链接过期后,若素材和源文件仍可用,可重新查询获取新链接;提交生成任务时继续使用 asset://素材ID,无需保存旧下载 URL。
素材或所属素材组删除、过期或被清理后,不能再创建引用它的新任务;仍持有旧 ID 或下载 URL 不会恢复引用权限。源文件保留也有独立策略,源文件缺失可能影响后续复用。生成视频的下载期限另见任务查询与下载,请自行保存需要长期留存的文件。
跨渠道复用与可用性
同一 API Key 下的托管素材可在支持素材能力的渠道间复用,客户端继续传原 asset:// ID。目标渠道首次使用时可能需要准备素材副本,因此提交耗时可能增加。GetAsset / ListAssets 返回的 Active 不保证目标渠道的素材副本已经就绪,也不保证所有模型都支持该输入。
跨渠道复制还依赖源文件可用;历史素材缺少源文件、源文件已过期或目标渠道不支持时,复用可能失败。保留素材 ID 和错误信息联系支持,不要通过反复创建素材尝试绕过错误。
全部素材操作
以下 10 个操作均使用 POST /volcengine/assets/?Action={action}&Version=2024-01-01 和 JSON 请求体。字段区分大小写,ID 使用对应创建响应的 Result.Id。
| Action | 用途 | 请求体示例 |
|---|---|---|
| CreateAssetGroup | 创建素材组 | {"Name":"产品展示素材","GroupType":"AIGC"} |
| GetAssetGroup | 查询素材组 | {"Id":"tsg_example"} |
| ListAssetGroups | 分页列出素材组 | {"PageNumber":1,"PageSize":20} |
| UpdateAssetGroup | 修改组名称或描述 | {"Id":"tsg_example","Name":"新组名","Description":"产品素材"} |
| DeleteAssetGroup | 删除素材组及组内素材 | {"Id":"tsg_example"} |
| CreateAsset | 从媒体 URL 创建素材 | {"GroupId":"tsg_example","Name":"产品正面","AssetType":"Image","URL":"https://example.com/product.jpg"} |
| GetAsset | 查询素材及状态 | {"Id":"tsa_example"} |
| ListAssets | 按组分页列出素材 | {"Filter":{"GroupIds":["tsg_example"]},"PageNumber":1,"PageSize":20} |
| UpdateAsset | 修改素材名称 | {"Id":"tsa_example","Name":"新素材名"} |
| DeleteAsset | 删除素材 | {"Id":"tsa_example"} |
旧版项目发现
curl --fail-with-body -sS "https://agent.tokensea.ai/v1/asset-projects" \
-H "Authorization: Bearer $TOKENSEA_API_KEY"
此接口供已有客户端查询项目标识,返回值可能为 default。新接入无需先查询或创建项目,可直接创建素材组。项目查询使用上述 GET 接口,不使用 Action=ListAssetProjects。
1. 创建素材组
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/volcengine/assets/?Action=CreateAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-asset-group-key" \
-d '{
"Name": "产品展示素材",
"GroupType": "AIGC"
}'
保存响应中的 Result.Id 作为素材组 ID,例如 tsg_example。以下 ID 均为占位,执行下一步前替换为实际返回值。ProjectName 可省略。
2. 从图片直链创建素材
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/volcengine/assets/?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-image-asset-key" \
-d '{
"GroupId": "tsg_example",
"Name": "产品正面",
"AssetType": "Image",
"URL": "https://example.com/product.jpg"
}'
保存 Result.Id 作为素材 ID,例如 tsa_example。创建响应不代表素材已就绪。即使创建返回错误,也请保留响应头 X-Seedance-Asset-Id(若有),按提交未确认说明核对。
3. 查询素材状态
curl --fail-with-body -sS "https://agent.tokensea.ai/volcengine/assets/?Action=GetAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"Id": "tsa_example"}'
间隔数秒查询,直到 Result.Status 为 Active 后再使用。若状态为 Failed,检查 Result.Error.Code、Result.Error.Message 和媒体直链,结束轮询;其中 SubmissionUnconfirmed 需要联系支持核对,不要直接重新创建。
| Result.Status | 处理方式 |
|---|---|
Processing | 素材仍在处理,间隔数秒查询同一 ID,并设置业务等待上限;等待超时不表示创建失败。 |
Active | 可按素材类型引用,目标渠道和模型的限制见跨渠道复用与可用性。 |
Failed | 停止轮询并检查错误;确认是媒体问题后修正输入,再作为新操作创建。提交未确认时先联系支持核对,不能换键重建。 |
{
"Result": {
"Id": "tsa_example",
"GroupId": "tsg_example",
"AssetType": "Image",
"Status": "Active"
}
}
素材处理失败响应示意(Result.Error 仅在有错误详情时返回):
{
"Result": {
"Id": "tsa_example",
"GroupId": "tsg_example",
"AssetType": "Image",
"Status": "Failed",
"Error": {
"Code": "SubmissionUnconfirmed",
"Message": "upstream acceptance is unconfirmed; reconcile before creating another asset"
}
}
}
素材处理失败与 HTTP 请求失败不同。本节 /volcengine/assets/ 接口的网关请求错误通常使用小写 error.code / error.message;上游错误也可能包含 ResponseMetadata.Error.Code / ResponseMetadata.Error.Message。请同时保留 HTTP 状态、请求 ID 和完整错误响应,不要统一按视频任务的错误字段解析。
{
"error": {
"code": "seedance_asset_error",
"message": "managed Seedance resource not found"
}
}
4. 引用素材生成视频
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-image-reference-key" \
-d '{
"model": "byteplus/dreamina-seedance-2-0-260128",
"content": [
{"type": "text", "text": "商品缓慢旋转展示,保持外观细节一致,柔和棚拍光线"},
{"type": "image_url", "image_url": {"url": "asset://tsa_example"}, "role": "reference_image"}
],
"duration": 5,
"ratio": "16:9",
"resolution": "720p",
"auto_create_assets": false
}'
保存创建响应中的 id,按照任务查询流程等待视频完成。asset:// 后填写完整素材 ID,不填写素材组 ID,也不把素材下载 URL 当作素材 ID。
5. 查询列表与修改名称
curl --fail-with-body -sS "https://agent.tokensea.ai/volcengine/assets/?Action=ListAssets&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Filter": {"GroupIds": ["tsg_example"]},
"PageNumber": 1,
"PageSize": 20
}'
ListAssets 和 ListAssetGroups 均支持页码分页。PageNumber 从 1 开始,默认 1,最大 1000000;PageSize 默认 20,取值 1–100。保持筛选条件和页大小不变,逐页增加页码。
页码分页响应示意,TotalCount 是符合筛选条件的资源总数,不是当前页条数:
{
"Result": {
"Items": [
{"Id": "tsa_example", "GroupId": "tsg_example", "AssetType": "Image", "Status": "Active"}
],
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 20
}
}
读取 Result.Items。当当前页为空,或 PageNumber × PageSize >= TotalCount 时结束;资源在翻页期间可能变化,页码分页不提供固定快照。
也可使用游标分页:首次以 MaxResults 指定每页条数(默认 10,取值 1–100),后续携带返回的 Result.NextToken,并保持筛选条件、排序和 MaxResults 不变。例如,下列 JSON 可替换上面 ListAssets 请求的请求体:
{
"Filter": {"GroupIds": ["tsg_example"]},
"MaxResults": 20
}
游标响应只包含 Result.Items 和可选的 Result.NextToken,没有 TotalCount、PageNumber 或 PageSize。没有 NextToken 即为最后一页。令牌有效期为一小时,仅适用于原 API Key 和原查询;过期后从第一页重新查询。两种分页参数不能混用。
curl --fail-with-body -sS "https://agent.tokensea.ai/volcengine/assets/?Action=UpdateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"Id": "tsa_example", "Name": "产品正面新版"}'
素材组还支持 GetAssetGroup、ListAssetGroups、UpdateAssetGroup。接口统一为 POST,查询参数中的 Action 区分操作;Version 使用 2024-01-01。
6. 删除不再需要的素材
以下请求会删除对应资源,仅在确认不再使用时执行。建议等待引用该素材的任务结束后,先删除组内素材,再删除空素材组。
curl --fail-with-body -sS "https://agent.tokensea.ai/volcengine/assets/?Action=DeleteAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"Id": "tsa_example"}'
curl --fail-with-body -sS "https://agent.tokensea.ai/volcengine/assets/?Action=DeleteAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"Id": "tsg_example"}'
删除后不要再创建引用该素材的新任务。
视频素材复用
需要多次参考同一段视频时,先按素材管理流程创建素材组,再从视频直链创建 Video 素材。将下面的素材组 ID、媒体 URL 和幂等键替换为实际值;此接口从 URL 获取媒体,不接收本地文件路径。
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/volcengine/assets/?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-video-asset-key" \
-d '{
"GroupId": "tsg_example",
"Name": "镜头运动参考",
"AssetType": "Video",
"URL": "https://example.com/motion.mp4"
}'
保存 Result.Id,以下以 tsa_video_example 为占位。用 GetAsset 查询该 ID,等待 Result.Status=Active 后再引用;失败或提交未确认时按前述规则处理。
curl --fail-with-body -sS "https://agent.tokensea.ai/volcengine/assets/?Action=GetAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"Id": "tsa_video_example"}'
使用支持参考视频的模型,设置 type: video_url、video_url.url: asset://完整素材ID 和 role: reference_video。视频时长、大小及输入组合仍需符合模型要求。
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-video-reference-key" \
-d '{
"model": "byteplus/dreamina-seedance-2-0-260128",
"content": [
{"type": "text", "text": "参考视频中的镜头运动,生成一段海边日落短片"},
{"type": "video_url", "video_url": {"url": "asset://tsa_video_example"}, "role": "reference_video"}
],
"duration": 5,
"ratio": "16:9",
"resolution": "720p",
"auto_create_assets": false
}'
保存视频任务 id,按任务查询流程获取结果。后续新任务可继续使用同一素材 ID,但每个新任务需使用新的幂等键。auto_create_assets 只自动处理 HTTP(S) 图片,不会自动上传视频或音频。
音频素材复用
先创建素材组,再将可访问的音频直链创建为 Audio 素材。下面的组 ID、URL 和幂等键均需替换为实际值。
curl --fail-with-body -sS --dump-header - "https://agent.tokensea.ai/volcengine/assets/?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKENSEA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: replace-with-unique-audio-asset-key" \
-d '{
"GroupId": "tsg_example",
"Name": "节奏参考",
"AssetType": "Audio",
"URL": "https://example.com/rhythm.mp3"
}'
保存 Result.Id,用 GetAsset 查询至 Result.Status=Active。以下以 tsa_audio_example 为音频素材 ID 占位,tsa_image_example 为另一个已就绪的图片素材 ID;将以下数组放入视频创建请求的 content,为新任务使用新的幂等键:
[
{"type": "text", "text": "参考图片中的主体和音频节奏,生成一段短片"},
{"type": "image_url", "image_url": {"url": "asset://tsa_image_example"}, "role": "reference_image"},
{"type": "audio_url", "audio_url": {"url": "asset://tsa_audio_example"}, "role": "reference_audio"}
]
请选择支持参考音频及该输入组合的模型。是否需要配合图片或视频,以及音频数量、大小和时长限制,以模型能力为准;auto_create_assets 不会自动转换音频 URL。
Seedance 常见问题
| 现象 | 排查与处理 |
|---|---|
| 模型不存在或无可用服务 | 核对完整模型 ID、API Key 的模型权限和余额;使用控制台或 /v1/models 确认可用模型。 |
| 401 / 403 或认证失败 | 检查 TokenSea API Key 和服务权限;确认无误后仍认证失败,请保留请求 ID 联系支持。 |
| 创建请求返回 409 | 检查错误信息和幂等重试规则。同键不同内容会冲突;处理中或未确认时,不要换键创建。 |
| SubmissionUnconfirmed / submission_unconfirmed | 保留素材 ID、任务 ID、幂等键和请求 ID,联系支持核对。视频预扣额度可能保留,详见提交未确认与费用。 |
| task_persistence_failed | 上游已受理,保留任务 ID 和返回的 recovery_token 联系支持恢复;不要重新提交。 |
| 素材必须为 Active | 查询 GetAsset,等待 Result.Status=Active 再引用;若为 Failed,检查 Result.Error。 |
| 素材为 Active,但生成时仍不可用 | 目标渠道可能仍需准备素材副本,也可能存在源文件或输入能力限制。保留 ID 和错误信息,参考跨渠道复用说明。 |
| 素材不存在或不属于当前用户 | 确认使用原 API Key、完整素材 ID,且素材及所属素材组未删除或过期。 |
| 无法读取媒体 / 创建素材失败 | 确认 URL 返回媒体文件、无登录限制、签名未过期;服务端可访问性也需满足。提交未确认时先核对,不要直接重新创建。 |
| ratio / resolution / duration 参数错误 | 按具体模型和输入模式调整;Seedance 2.5 首帧、首尾帧使用 adaptive。 |
| 查询返回 429 / 5xx | 降低频率并退避重试查询,保持同一个任务 ID。创建请求应另按幂等重试规则处理。 |
| 长时间 queued / running | 继续查询原任务并设置业务等待上限;等待超时不代表任务失败。 |
| succeeded 但视频无法下载 | 使用创建时相同的 API Key 调用 /v1/videos/{task_id}/content,检查认证和视频有效期;仍失败时保留任务 ID 联系支持。 |
| 为什么不能照抄 /v1 的响应路径? | 本页 V3 从 id、status、content.video_url 取值;不要混用兼容接口的字段结构。 |
联系支持时请提供任务或素材 ID、模型 ID、请求时间、HTTP 状态、幂等键及错误信息;如响应含 X-Oneapi-Request-Id、ResponseMetadata.RequestId 或 X-Seedance-Asset-Id,请一并提供。返回的 recovery_token 仅通过支持渠道提供。无需提供完整 API Key。
后台配置说明
登录 TokenSea 控制台后,可以管理 API 令牌、查看余额和使用记录,并在个人设置中调整通知方式。以下说明面向使用平台的用户;可见菜单和可用功能以账号权限及平台开放情况为准。
账户与安全
进入「个人设置」查看和维护账号信息,按页面提示绑定邮箱、修改密码或设置可用的安全验证方式。账号绑定邮箱可作为邮件通知的默认收件地址;如需由财务或团队成员接收通知,可以另行设置通知邮箱。
账号密码、API Key 和安全验证凭据请妥善保管。向平台反馈问题时,提供模型名称、调用时间、请求 ID 和错误信息即可,不要发送完整密钥。
令牌管理
进入「令牌管理」创建调用模型使用的 API Key。建议按应用或项目分别创建并命名,方便在使用日志和账单中区分费用来源。创建后按照接口文档配置到应用中。
根据需要设置令牌额度、有效期、允许使用的模型、分组和请求频率限制。令牌额度用于限制该令牌可用的消费额度,实际调用还需满足账号余额或订阅、模型权限等条件。密钥泄露或应用停用时,请及时禁用或删除对应令牌。
余额与账单
「钱包管理」用于查看余额和平台提供的充值方式;「使用日志」用于核对每次调用的模型、令牌、用量和费用;「用户账单」用于查看汇总明细。查询时注意选择正确的日期和筛选条件。
费用按调用当时的计费规则记录。原价用量费用乘以生效倍率得到消费金额;例如,原价用量费用为 10 元、生效倍率为 0.8,消费金额为 8 元。按次计费、缓存用量及退款等以对应明细为准,逐次计费取整可能产生尾差。
邮件账单会展示历史原价、生效倍率和记录金额,已经计入的倍率不会重复相乘。约定在消费之后另行结算的折扣,不会再次从邮件账单中扣减;这类消费仍按调用时记录的费用出账。账单用于核对消费,不会因发送邮件再次扣款。
邮件通知
在哪里设置:进入「个人设置 → 其他设置 → 通知配置」。余额告警和每日账单共用「通知邮箱」。可以添加多个邮箱,输入后按回车,也可以用逗号或分号分隔;留空时使用账号绑定的邮箱。修改后请先点击保存。
余额告警:将「通知方式」设为「邮件通知」,并设置合适的「预警阈值」。钱包或订阅剩余额度在调用结算时低于阈值,系统会按通知规则发送提醒;仅保存阈值不会立即发送测试邮件。同类通知受频率限制,不会每次调用都重复发送。告警邮件不能代替余额检查,建议提前充值。
开启每日账单:打开「接收每日账单邮件」并保存。平台也需要启用每日账单邮件,两个开关均开启后才会发送。每日账单始终通过邮件发送,即使余额告警选择了其他通知方式,也仍使用这里设置的通知邮箱。关闭每日账单开关后,不再接收每日账单,余额告警仍按自己的设置执行。
自动发送时间:平台默认在每天北京时间 08:00 发送前一天的账单,实际时间以平台配置为准。统计范围为前一天北京时间 00:00 至次日 00:00;例如,11 月 10 日发送的是 11 月 9 日的消费明细。有消费或退款等调整时出账,无记录时跳过。首次开启默认从昨日账单开始,不追发更早历史账单。
预览和手动发送:在通知配置中点击「预览昨日日账单」可以查看明细和收件人;确认接收开关与邮箱已保存后,可以点击「发送昨日日账单」。同一用户同一天的账单只发送一次,手动发送成功后不会再自动发送一份;已经自动发送的账单也不会通过按钮重复发送。发送失败时系统会安排重试。
账单包含什么:账单按使用分组、令牌、模型、消费或退款类型以及历史价格和倍率拆分明细,展示调用记录数、输入与输出用量、缓存用量、原价、生效倍率和金额,并列出消费合计、退款合计与净消费。金额以历史实际记录为准,缺少历史价格或倍率时会标明,不按当前价格重新计算。
没有收到邮件怎么办:先确认通知邮箱或账号绑定邮箱填写正确、设置已经保存,并检查垃圾邮件。如果是每日账单,再确认已开启接收、昨日有消费或调整,以及该日账单是否已经发送。如果仍未收到或页面提示发送失败,请联系平台管理员检查邮件服务配置,并提供用户名、账单日期和提示信息。
错误码
| HTTP | 错误码 | 说明 | 解决方案 |
|---|---|---|---|
| 400 | invalid_request | 请求参数错误 | 检查 messages、model、prompt |
| 400 | model_not_found | 模型不存在 | 确认模型 ID |
| 401 | — | API Key 无效 | 确认 Key 来源 |
| 403 | — | 权限不足 | 确认已开通对应服务 |
| 409 | 以实际响应为准 | Seedance 请求冲突、处理中或提交未确认等 | 检查错误信息;涉及幂等请求时保留原键,按重试规则处理 |
| 429 | — | 频率超限 | 降低频率 |
| 500 | — | 服务器错误 | 查询可退避重试;Seedance 创建请求按幂等重试规则处理,提交未确认时联系支持 |
| 503 | model_not_found | 服务暂不可用 | 换模型或联系管理员 |
FAQ
哪些模型返回 reasoning_content?
glm-5、glm-5.1、qwen3.6-plus 默认开启,以 content 字段为准。
如何接入 Seedance 和复用参考素材?
从Seedance 视频生成开始;单次图片参考可使用自动临时素材,多次复用请使用素材管理接口。