大模型 API 接入文档
本文档提供文本、图片、视频、语音、多模态向量和 3D 模型的标准接入方式。实际可用模型以当前 API Key 调用 GET /v1/models 的返回结果为准。
https://token.axicomin.cn/
快速开始
#调用模型使用平台 API Key。首次接入时,先配置好凭证,再从模型列表中选出当前账户可用的模型。
创建模型 API Key
- 登录平台控制台,进入 API 密钥。
- 新建密钥并起一个便于识别的名称,例如 `development。按当前控制台提供的选项设置分组或使用限制。
- 将完整密钥保存到密码管理器或服务端的环境变量。密钥疑似泄露时,在控制台停用或删除旧密钥并替换应用配置。
验证连接
BASE_URL="https://token.axicomin.cn"
API_KEY="<YOUR_API_KEY>"
curl --fail-with-body -sS "$BASE_URL/v1/models" \
-H "Authorization: Bearer $API_KEY"请求成功时,从返回的 `data 数组读取模型 ID。调用模型前先核对 ID、账号权限和 对应协议。需要查看账户额度或通过 API 管理密钥时,应使用 个人令牌。
全局配置
#BASE_URL="https://token.axicomin.cn"
API_KEY="<YOUR_API_KEY>"鉴权
除 Seedance 素材资产库可选的 Ark AK/SK 兼容认证外,所有接口使用平台 API Key 鉴权:
Authorization: Bearer <YOUR_API_KEY>请求追踪
客户端应在每次请求后记录响应头中的 X-Oneapi-Request-Id。该值是问题排查所需的日志定位 ID;反馈接口问题时请一并提供。
查询可用模型
#curl "$BASE_URL/v1/models" \
-H "Authorization: Bearer $API_KEY"请求体中的 model 请使用该接口返回的模型名。
模型接口索引
#先查询当前 API Key 可用的模型,再按照模型支持的协议选择调用入口。
| 任务 | 接口与示例 |
|---|---|
| 文本对话与生成 | Chat Completions、Responses、Anthropic Messages、Gemini 原生接口 |
| 图片生成与编辑 | Gemini、GPT Image、Seedream、Wan Image、Qwen Image、Z-Image |
| 视频生成与编辑 | Seedance、Wan 视频、MiniMax-H3、Happyhorse |
| 视频素材与认证 | Seedance 素材资产库 |
| 语音 | 语音合成 TTS、实时语音识别 ASR |
| 向量与 3D | 多模态向量、3D 模型生成 |
接入规范
#| 项目 | 接入要求 |
|---|---|
| 接口地址 | 请求统一使用 https://token.axicomin.cn/。SDK 的地址可以按所选协议添加 /v1。 |
| 模型选择 | 先调用 `GET /v1/models。更换模型时,同时确认该模型接受的协议、参数和输入类型。 |
| 请求追踪 | 记录响应头 `X-Oneapi-Request-Id,排查故障时提供该 ID、请求时间和接口路径。日志应省略完整密钥和敏感请求内容。 |
| 失败处理 | 检查 HTTP 状态与响应体。先修正鉴权和参数错误。遇到限流或临时服务故障时,使用有重试上限的指数退避。 |
| 超时与异步 | 按请求类型设置连接和读取超时。创建异步任务后保存任务 ID,再按接口建议间隔查询状态。 |
原生协议、OpenAI 兼容协议和用户级接口使用不同的路径及授权方式。可从 全局配置、用户与密钥管理 和 错误处理 查看对应细节。
错误处理与重试
#- 对
HTTP 429和临时性5xx响应采用带抖动的指数退避,不要无间隔重试。 - 视频任务创建成功后按建议间隔轮询,不要高频查询任务状态。
- 写请求遇到网络超时且无法确认服务端是否接收时,优先复用原
Idempotency-Key重试。 - 保留响应头
X-Oneapi-Request-Id,用于接口问题定位。 - TTS 返回二进制音频;图片模型可能返回 Base64 或 URL;视频模型返回异步任务 ID。客户端应按接口响应类型分别处理。
个人令牌
#查询账户或管理 API Key 时,在 Authorization 请求头中使用个人令牌。模型接口(例如 GET /v1/models)使用单独创建的 API Key。
登录控制台,在「安全与访问」的「会话与访问」下找到「访问令牌」,选择「生成」。重新生成后,旧令牌立即失效。将新令牌保存在环境变量或凭据库,避免把它写入日志和共享文件。 安全与访问
BASE_URL="https://token.axicomin.cn"
PERSONAL_ACCESS_TOKEN="<PERSONAL_ACCESS_TOKEN>"
AUTH_HEADER="Authorization: Bearer $PERSONAL_ACCESS_TOKEN"后续账户接口示例沿用这些变量。
| 要做什么 | 查看文档 |
|---|---|
| 查询当前余额和累计用量 | 账户额度 |
| 按时间、模型或 Key 查询消耗与请求日志 | 用量与明细 |
| 创建、停用或管理某个 Key 的配置和额度 | API Key 管理 |
账户额度
#使用个人令牌请求 GET /api/user/self,从响应 JSON 的 data 对象读取余额和累计用量。
curl "$BASE_URL/api/user/self" -H "$AUTH_HEADER"| 字段 | 内容 |
|---|---|
data.quota |
当前可用额度 |
data.used_quota |
累计消耗的额度 |
data.request_count |
累计请求笔数 |
{
"success": true,
"data": {
"quota": 750000,
"used_quota": 250000,
"request_count": 42
}
}默认每 500000 个额度单位等于 1 USD。例如,quota 为 750000 时,默认折合 1.50 USD。显示金额时按站点配置换算。 参考文档 · 账户额度
用量与明细
#这两类查询使用个人令牌,日志接口限频为每分钟 60 次。收到 HTTP 429 时,根据响应头 Retry-After 等待再重试,并错开汇总和明细的刷新。
查询用量汇总
GET /api/log/self/stat 用于查看符合筛选条件的额度消耗。
| 查询参数 | 用法 |
|---|---|
start_timestamp、end_timestamp |
必填,Unix 秒级时间戳,查询范围不足 31 天 |
model_name |
可选,限定模型 |
token_name |
可选,精确匹配 API Key 名称 |
START_TIMESTAMP=1784548800
END_TIMESTAMP=1784635200
curl --get "$BASE_URL/api/log/self/stat" \
-H "$AUTH_HEADER" \
--data-urlencode "start_timestamp=$START_TIMESTAMP" \
--data-urlencode "end_timestamp=$END_TIMESTAMP"data.quota 是该范围内的消费额度,按默认换算除以 500000 得到美元金额。data.rpm 和 data.tpm 统计符合筛选条件的最近 60 秒数据,分别表示请求数和输入、输出 Token 之和。
查询并翻阅用量明细
GET /api/log/self 返回逐条日志。可以传与汇总接口相同的时间和名称筛选,此处均为可选参数。还可以指定 request_id 精确定位请求。
| 查询参数 | 用法 |
|---|---|
page_size |
单批条数,默认 10,上限 100 |
type |
2 仅返回消费记录,0 返回各类日志 |
cursor |
首批省略。后续使用上一批的 data.next_cursor |
curl --get "$BASE_URL/api/log/self" \
-H "$AUTH_HEADER" \
--data-urlencode 'type=2' \
--data-urlencode 'page_size=25' \
--data-urlencode "start_timestamp=$START_TIMESTAMP" \
--data-urlencode "end_timestamp=$END_TIMESTAMP"data.items 按创建时间从新到旧排列。消费条目可包含 created_at、type、model_name、token_name、quota、prompt_tokens、completion_tokens 和 request_id。响应还提供实际使用的 data.page_size、data.has_more 和 data.next_cursor。当 has_more 为 true 时,保持原有筛选条件,在下一次请求中加上 --data-urlencode "cursor=$NEXT_CURSOR",其中 NEXT_CURSOR 为原样保存的 next_cursor。最后一批的游标为空字符串。接口不提供日志总数。
客户端应检查 HTTP 状态与响应的 success 字段。省略时间范围会检索全部可用日志,日常查询可限定时间并缓存结果。 参考文档 · 用量与明细
API Key 管理
#本节操作统一使用个人令牌。路径中的 {id} 是 API Key 的数字 ID,可以从创建结果或列表中获取。示例中的 API_KEY_ID 需要赋为目标 ID。
获取可用分组
GET /api/user/self/groups 返回以分组名为对象键的 data。每组的 desc 说明用途,ratio 表示倍率,可能为数字或字符串。创建和配置请求的 group 可使用返回的分组名。
curl "$BASE_URL/api/user/self/groups" -H "$AUTH_HEADER"创建与配置 API Key
使用 POST /api/token/ 创建 Key。成功后记录 data.token_id。如需获取实际密钥,请再调用完整 Key 接口。用 POST /api/token/{id}/config 修改配置,服务端只改动请求中给出的字段。配置成功会返回更新后的对象,其中 key 已脱敏。
| JSON 字段 | 应用场景与取值 |
|---|---|
name |
创建或配置。名称最长 50 个字符 |
expired_time |
创建或配置。Unix 秒级时间戳,-1 表示无到期时间 |
unlimited_quota |
创建或配置。布尔值,启用后忽略初始剩余额度 |
model_limits_enabled、model_limits |
创建或配置。用布尔值启用模型限制,用英文逗号分隔允许的模型名 |
allow_ips |
创建或配置。每行一个 IP 或 CIDR,空字符串允许所有地址 |
group |
创建或配置。所选分组名称 |
auto_groups |
当 group 为 auto 且使用自定义自动分组时,必须传入分组名数组 |
cross_group_retry |
创建或配置。布尔值,仅 group 为 auto 时控制是否跨组重试 |
remain_quota |
创建。限额 Key 的初始剩余额度为 0 至 500000000000000 之间的整数 |
status |
配置。整数 1 启用,2 禁用 |
curl -X POST "$BASE_URL/api/token/" \
-H "$AUTH_HEADER" \
-H 'Content-Type: application/json' \
--data '{"name":"doc-example","group":"default","unlimited_quota":false,"remain_quota":1500000}'API_KEY_ID="<API_KEY_ID>"
curl -X POST "$BASE_URL/api/token/$API_KEY_ID/config" \
-H "$AUTH_HEADER" \
-H 'Content-Type: application/json' \
--data '{"allow_ips":"192.0.2.42/32"}'查询列表或单个配置
GET /api/token/ 接收 p 和 page_size。p 从 1 开始,默认 1,每页默认 10 条、上限 100 条。返回 data.page、data.page_size、data.total 和 data.items。单个配置使用 GET /api/token/{id},返回与 data.items[] 同一结构的对象。
curl "$BASE_URL/api/token/?p=1&page_size=20" -H "$AUTH_HEADER"
curl "$BASE_URL/api/token/$API_KEY_ID" -H "$AUTH_HEADER"| 配置字段 | 内容 |
|---|---|
id、name、key |
Key 的 ID、名称以及遮盖部分字符的密钥 |
status |
1 启用、2 禁用、3 已过期、4 额度耗尽 |
remain_quota、used_quota、unlimited_quota |
剩余额度、已消耗额度以及不限额标记 |
created_time、accessed_time、expired_time |
创建、最近访问和到期的 Unix 秒级时间戳。expired_time 为 -1 时永久有效 |
group、auto_groups、cross_group_retry |
所选分组、自定义自动分组和跨组重试设置。未指定自定义列表时 auto_groups 为 null |
model_limits_enabled、model_limits、allow_ips |
模型限制开关、逗号分隔的模型列表和 IP 白名单 |
获取完整 Key
POST /api/token/{id}/key 在 data.key 中返回可用于模型调用的密钥。通过服务端安全地保存和使用该值,避免将其返回给浏览器或记录到日志。密钥泄漏时,及时禁用或删除相应的 Key。
curl -X POST "$BASE_URL/api/token/$API_KEY_ID/key" -H "$AUTH_HEADER"调整额度
POST /api/token/{id}/quota 以原子方式修改限额 Key 的余额。必填请求头 Idempotency-Key 必须为 1 至 128 个非控制字符,并为同一 API Key 的每项新操作使用一个唯一值。重试原请求时,保留相同的幂等键和请求内容,避免重复调整。
| 必填 JSON 字段 | 取值 |
|---|---|
action |
increase 增加、decrease 扣减、set 设定剩余额度 |
amount |
0 至 500000000000000 之间的整数。增加和扣减要求大于 0 |
无限额 Key 不适用此操作。扣减超过余额或以相同幂等键提交不同参数时,服务端返回 HTTP 409。
QUOTA_OPERATION_KEY="<UNIQUE_OPERATION_ID>"
curl -X POST "$BASE_URL/api/token/$API_KEY_ID/quota" \
-H "$AUTH_HEADER" \
-H "Idempotency-Key: $QUOTA_OPERATION_KEY" \
-H 'Content-Type: application/json' \
--data '{"action":"increase","amount":250000}'响应 data 包含 token_id、action、amount、before_quota、after_quota 和 operation_id,另有 replayed 标记同一操作的重放结果。
查询指定 Key 的额度与日志
两个查询使用每分钟 60 次的限频规则,收到 HTTP 429 时按 Retry-After 延迟重试。
GET /api/token/{id}/usage 返回 data.object 为 token_usage 的对象。total_used 是已用额度,total_available 是可用余额,total_granted 等于两者之和。还会返回 token_id、name、unlimited_quota、model_limits_enabled 和允许模型到 true 的 model_limits 映射。expires_at 为 Unix 秒级时间戳,0 表示无到期时间。
curl "$BASE_URL/api/token/$API_KEY_ID/usage" -H "$AUTH_HEADER"使用 GET /api/token/{id}/logs 获取指定 Key 的历史用量。可选 limit 取值为 1 到 100,默认 50。start_timestamp 和 end_timestamp 为可选的正整数秒级时间戳,结束时间应大于或等于开始时间。首次请求省略 cursor。
curl --get "$BASE_URL/api/token/$API_KEY_ID/logs" \
-H "$AUTH_HEADER" \
--data-urlencode 'limit=20'data.items 按时间从新到旧排列。每条记录包括展示序号 id、记录时间 created_at、类型 type、token_id、token_name、model_name、额度变化 quota、prompt_tokens、completion_tokens、耗时 use_time(秒)、is_stream 以及 request_id。
响应会回显 limit、token_id、start_timestamp 和 end_timestamp。未指定的时间边界回显为 0。当 data.has_more 为 true 时,保持原有查询参数,追加 --data-urlencode "cursor=$NEXT_CURSOR",将 data.next_cursor 原样带入下一次请求。没有更多记录时,data.next_cursor 为空字符串。
额度显示换算
余额、调整请求的 amount、调整前后的 before_quota 与 after_quota、日志中的 quota 均以额度单位计数。默认 QuotaPerUnit 为 500000,以站点实际配置为准。
| 显示方式 | 计算 |
|---|---|
| 美元 | quota / QuotaPerUnit |
| 人民币 | quota / QuotaPerUnit × USDExchangeRate,其中 USDExchangeRate 为站点配置的一美元所兑换的人民币数值 |
| Token 模式 | 显示原始 quota |
例如,默认换算下要增加 2 USD 对应的额度,amount 应填 1000000。 参考文档 · API Key 管理
删除 API Key
确认该 Key 已停止使用后,通过 DELETE /api/token/{id} 删除。成功时 success 为 true,原 Key 随即失效。
curl -X DELETE "$BASE_URL/api/token/$API_KEY_ID" -H "$AUTH_HEADER"Agent 工具接入总览
#先在平台创建 API Key,再使用模型列表确认该密钥可以访问哪些模型。把以下指南中的 <YOUR_API_KEY> 和 <MODEL_ID> 替换为平台密钥和返回的完整模型 ID。
| 工具 | 调用协议 | 在工具中填写的 Base URL |
|---|---|---|
| Claude Code | Anthropic Messages · POST /v1/messages |
https://token.axicomin.cn |
| Codex | OpenAI Responses · POST /v1/responses |
https://token.axicomin.cn/v1 |
| OpenCode、OpenClaw、Hermes、WorkBuddy | OpenAI Chat Completions · POST /v1/chat/completions |
https://token.axicomin.cn/v1 |
命令行示例通过 AXICOMIN_API_KEY 读取密钥。用环境变量或应用的凭据存储提供密钥,避免把真实值写入项目配置、日志或截图。在启动工具的同一个终端中设置变量,例如:
export AXICOMIN_API_KEY="<YOUR_API_KEY>"$env:AXICOMIN_API_KEY = "<YOUR_API_KEY>"模型还需要支持所选工具的协议及工具调用。配置完成后可以先发送一个简短的对话,再验证一项只读操作,例如概述当前目录。
| 现象 | 检查项 |
|---|---|
401 |
密钥是否有效,启动进程能否读取密钥,客户端是否按该指南发送 Bearer 凭据 |
404、找不到模型 |
Base URL 的 /v1 是否正确,模型 ID 是否逐字匹配 模型列表 的返回值 |
| 能对话但无法调用工具 | 模型是否支持工具调用,当前工作目录和客户端权限是否允许该操作 |
Claude Code
#Claude Code 使用 Anthropic Messages,调用 POST /v1/messages。
安装与版本检查
在 macOS、Linux 或 WSL 中运行:
curl -fsSL https://claude.ai/install.sh | bash
claude --version在 Windows PowerShell 中运行:
irm https://claude.ai/install.ps1 | iex
claude --version在 Windows 命令提示符中运行:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
claude --version在终端启动
在已设置 AXICOMIN_API_KEY 的终端中执行以下配置。Base URL 填站点根地址,Claude Code 会拼接 /v1/messages。ANTHROPIC_AUTH_TOKEN 对应 Authorization: Bearer。
export ANTHROPIC_BASE_URL="https://token.axicomin.cn"
export ANTHROPIC_AUTH_TOKEN="$AXICOMIN_API_KEY"
export ANTHROPIC_MODEL="<MODEL_ID>"
claudeWindows PowerShell 中使用以下写法:
$env:ANTHROPIC_BASE_URL = "https://token.axicomin.cn"
$env:ANTHROPIC_AUTH_TOKEN = $env:AXICOMIN_API_KEY
$env:ANTHROPIC_MODEL = "<MODEL_ID>"
claude将地址和默认模型保存到用户配置
把以下 env 项合并到 ~/.claude/settings.json,继续通过终端环境提供 ANTHROPIC_AUTH_TOKEN。
{
"env": {
"ANTHROPIC_BASE_URL": "https://token.axicomin.cn",
"ANTHROPIC_MODEL": "<MODEL_ID>"
}
}启动后用 /status 检查配置,发送一句问候验证连接。若已有登录状态导致鉴权冲突,可在 Claude Code 中执行 /logout,再从配置好环境的终端启动。
Codex
#Codex CLI 可以把 Responses API 路由到自定义供应商。安装客户端并确认版本后,从能读取 AXICOMIN_API_KEY 的终端启动。
npm install -g @openai/codex
codex --version配置模型供应商
在用户级 ~/.codex/config.toml 中合并以下字段。将 model 填为支持 Responses API 的模型 ID。自定义供应商名称 axicomin 要与 model_provider 的值一致。
model = "<MODEL_ID>"
model_provider = "axicomin"
[model_providers.axicomin]
name = "Axicomin"
base_url = "https://token.axicomin.cn/v1"
env_key = "AXICOMIN_API_KEY"
wire_api = "responses"自定义供应商由用户级配置载入。Codex 会忽略项目级配置中的 model_provider 和 model_providers。保存后在项目目录启动:
codex请它概述当前目录来验证连接。收到 401 时检查环境变量是否随进程启动传入。请求地址错误时,检查 wire_api 和 Base URL 的 /v1。
OpenCode
#本章目录
OpenCode 的 OpenAI Compatible 适配器调用 POST /v1/chat/completions。在支持 Bash 的环境中可以运行 OpenCode 2 的安装脚本。安装后在启动终端设置 AXICOMIN_API_KEY。
curl -fsSL https://opencode.ai/v2/install | bash
opencode --version配置项目
在项目根目录的 opencode.json 合并供应商定义。两个 <MODEL_ID> 均填写同一个完整模型 ID。以下示例使用新版 providers 配置。
{
"$schema": "https://opencode.ai/config.json",
"model": "axicomin/<MODEL_ID>",
"providers": {
"axicomin": {
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "https://token.axicomin.cn/v1",
"apiKey": "{env:AXICOMIN_API_KEY}"
},
"models": {
"<MODEL_ID>": {}
}
}
}
}旧版 OpenCode 配置示例
如果客户端使用 provider 配置格式,使用这一版本的 opencode.json 示例:
{
"$schema": "https://opencode.ai/config.json",
"model": "axicomin/<MODEL_ID>",
"provider": {
"axicomin": {
"npm": "@ai-sdk/openai-compatible",
"name": "Axicomin",
"options": {
"baseURL": "https://token.axicomin.cn/v1",
"apiKey": "{env:AXICOMIN_API_KEY}"
},
"models": {
"<MODEL_ID>": { "name": "Axicomin 模型" }
}
}
}
}验证模型
运行 opencode 后,通过 /models 查看自定义模型并发送消息。列表中没有模型时,核对配置位置和供应商 ID。若鉴权失败,检查当前进程是否能解析 {env:AXICOMIN_API_KEY}。
OpenClaw
#OpenClaw 的 openai-completions 适配器调用 POST /v1/chat/completions。
安装与设置密钥
在 macOS、Linux 或 WSL 中运行:
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version在 Windows PowerShell 中运行:
iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw --version在用户配置目录 ~/.openclaw/.env 中提供密钥:
AXICOMIN_API_KEY=<YOUR_API_KEY>注册供应商和模型
把以下字段合并到 ~/.openclaw/openclaw.json。模型列表中的 id 填原始 ID,选择默认模型时使用 axicomin/<MODEL_ID>。请保留已有的 Gateway、渠道和其他供应商配置。
{
"agents": {
"defaults": {
"model": { "primary": "axicomin/<MODEL_ID>" }
}
},
"models": {
"mode": "merge",
"providers": {
"axicomin": {
"baseUrl": "https://token.axicomin.cn/v1",
"apiKey": "${AXICOMIN_API_KEY}",
"api": "openai-completions",
"models": [
{ "id": "<MODEL_ID>", "name": "Axicomin 模型" }
]
}
}
}
}校验并测试
openclaw config validate
openclaw models list
openclaw models set "axicomin/<MODEL_ID>"若 Gateway 已作为服务运行,更新 .env 后使用 openclaw gateway restart 重新加载密钥。列表中出现模型后发送一条测试消息。配置校验失败时,先修正报错位置再重新加载。 OpenClaw Gateway 命令
Hermes
#在 Hermes 中添加自定义 OpenAI 兼容端点,通过 POST /v1/chat/completions 访问模型。
安装客户端
在 macOS、Linux 或 WSL 中运行:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash在 Windows PowerShell 中运行:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)安装后重新打开终端,让当前会话读取更新后的命令路径。
配置和验证模型
启动模型配置向导:
hermes model| 向导字段 | 填写值 |
|---|---|
| Provider | Custom endpoint |
| API Base URL | https://token.axicomin.cn/v1 |
| API mode(若显示) | Chat Completions(chat_completions) |
| API Key | <YOUR_API_KEY> |
| Model name | <MODEL_ID> |
| Context length(若显示) | 所选模型实际支持的上下文长度 |
向导负责管理用户目录中的 ~/.hermes/config.yaml 和 ~/.hermes/.env。其中可能包含密钥,保存于本机即可。完成后打开交互界面,检查供应商是否显示为 custom 或向导中自定义的名称,再确认模型 ID 并发送一条消息。
hermes --tui若无法连接,先运行 hermes doctor。再通过 hermes model 核对协议、Base URL、密钥和模型 ID。
WorkBuddy
#WorkBuddy 的自定义模型在应用界面中配置,调用 POST /v1/chat/completions。下载并安装客户端后登录。 WorkBuddy 官网
添加自定义模型
- 打开首页输入框右下角的模型选择器,选择 配置自定义模型。
- 进入模型设置,点击 添加模型。在供应商列表的 其他 分组选择 自定义。
- 填写下表中的三项。高级配置中的 自定义协议 保持关闭。
- 点击 测试连接。测试通过后点击 保存。
| 字段 | 填写值 |
|---|---|
| 接口地址 | https://token.axicomin.cn/v1 |
| API Key | 平台密钥原值,去除首尾空格 |
| 模型名称 | 模型列表 返回的完整模型 ID |
选择并验证
回到首页,打开模型选择器,在 自定义模型 分组选择刚保存的模型。发送一条短消息后,核对回复下方的模型名称。
| 现象 | 处理方式 |
|---|---|
| 连接失败或密钥无效 | 从平台重新复制 API Key,检查是否带有首尾空格。 |
| 找不到接口 | 核对接口地址是否以 /v1 结尾,并检查 自定义协议 是否关闭。 |
| 模型不存在或无权限 | 核对完整模型 ID,并检查该模型是否在当前密钥的模型列表中。 |
| 保存后找不到模型 | 回到首页,在输入框的模型选择器中展开 自定义模型。 |
Chat Completions API
#- 协议:OpenAI Chat Completions 兼容协议
- 接口:
POST /v1/chat/completions
curl "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{"role": "user", "content": "请用一句话介绍你自己"}
],
"max_tokens": 512
}'响应文本位于 choices[0].message.content。部分推理模型会消耗较多输出 token,应设置足够的 max_tokens。
流式调用与参数
在请求中设置 stream: true 后,响应通过 SSE 发送。跳过空增量,从 choices[].delta.content 逐段拼接文本,收到 data: [DONE] 时结束。需要在流末尾读取用量时,可设置 stream_options.include_usage: true。
| 参数 | 用途 |
|---|---|
max_completion_tokens |
限制部分兼容模型的输出与推理 Token 总量。 |
reasoning_effort |
对支持该参数的模型设置推理强度。 |
response_format |
选择受支持的输出结构,例如 {"type":"json_object"}。 |
tools、tool_choice、parallel_tool_calls |
定义可用工具,以及何时、是否并行调用。 |
curl -N "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [{"role":"user","content":"列出三种给室内植物浇水的注意事项。"}],
"stream": true,
"stream_options": {"include_usage": true},
"max_tokens": 512
}'请求与响应字段
| 请求字段 | 类型 | 用途 |
|---|---|---|
model |
string,必填 | 填写当前密钥可访问的模型 ID。 |
messages |
array,必填 | 按对话顺序排列消息,包含 role 和 content。纯文本直接使用字符串,内容数组的支持情况由模型决定。 |
stream |
boolean | 默认 false。设为 true 时逐段接收内容。 |
temperature、top_p |
number | 分别控制采样温度和核采样范围。需要调节时通常选用其中一个。 |
stop |
string 或 array | 对支持停止序列的模型,命中任一指定序列时结束输出。 |
| 响应字段 | 读取方式 |
|---|---|
id、model、created |
响应标识、服务返回的模型名和创建时间戳。 |
choices[].message |
非流式完整消息。工具调用时,content 可以为空。 |
choices[].delta |
流式增量,可能只更新角色或工具调用。输出文本时只拼接有值的 delta.content。 |
choices[].finish_reason |
常见值有 stop、length 和 tool_calls。 |
usage |
查看 prompt_tokens、completion_tokens 和 total_tokens。请求流式用量时,最后的用量块可能没有候选项。 |
Python SDK 示例
安装 openai 并设置 API_KEY 环境变量。下例依次发送非流式与流式请求,按需保留其中一种调用。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["API_KEY"],
base_url="https://token.axicomin.cn/v1",
)
model = os.getenv("MODEL_ID", "deepseek-v4-flash")
messages = [{"role": "user", "content": "用两句话介绍白露节气。"}]
completion = client.chat.completions.create(model=model, messages=messages)
print(completion.choices[0].message.content or "")
with client.chat.completions.create(
model=model,
messages=messages,
stream=True,
stream_options={"include_usage": True},
) as stream:
for chunk in stream:
if chunk.choices:
text = chunk.choices[0].delta.content
if text:
print(text, end="", flush=True)
if chunk.usage is not None:
print(f"\n总 token:{chunk.usage.total_tokens}")
print()Responses API
#- 协议:OpenAI Responses
- 接口:
POST /v1/responses
curl "$BASE_URL/v1/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"input": "请用一句话介绍你自己",
"max_output_tokens": 512
}'非流式响应文本位于 output 数组中 message 项的 content[].text;使用 OpenAI SDK 时可读取 response.output_text。流式调用设置 stream: true,文本增量位于 response.output_text.delta 事件的 delta 字段。
多轮上下文与完成状态
input 可为字符串或结构化输入项数组,instructions 可单独指定指令。支持多轮关联的模型可将上一轮响应的 id 作为下一轮的 previous_response_id。reasoning、text 和 tools 分别配置推理、输出格式和工具调用。用量见 usage.input_tokens 和 usage.output_tokens。如果响应失败或未完成,查看 error 或 incomplete_details。
流式调用逐条处理 SSE,使用 response.output_text.delta 拼接文本并处理完成和错误事件。使用 OpenAI 兼容 SDK 时,SDK 的基础地址应包含 /v1,例如 https://token.axicomin.cn/v1。
请求与响应字段
| 请求字段 | 类型 | 用途 |
|---|---|---|
model |
string,必填 | 填写支持 Responses API 的模型 ID。 |
input |
string 或 array,必填 | 单段文本或结构化输入项。 |
instructions |
string | 为本轮输入附加指令。 |
max_output_tokens |
integer | 限制输出 token 数量,包含推理过程使用的输出 token。 |
stream |
boolean | 默认 false。设为 true 时返回 SSE 事件。 |
tools、tool_choice |
array、string 或 object | 提供可调用工具并控制调用策略。 |
store、previous_response_id |
boolean、string | 控制响应保存并关联前一轮。使用前确认模型和接入渠道支持。 |
| 响应字段 | 读取方式 |
|---|---|
id、status |
响应 ID 和处理状态。关注 completed、failed 和 incomplete。 |
output |
输出项数组。遍历 type: "message" 的输出项,读取其中 type: "output_text" 的内容。 |
usage |
记录 input_tokens、output_tokens 与 total_tokens。 |
error、incomplete_details |
分别定位失败和未完成的原因。 |
使用 cURL 接收事件流
curl --no-buffer --fail-with-body "https://token.axicomin.cn/v1/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-pro",
"input": "列出两个减少会议时间的方法。",
"max_output_tokens": 512,
"stream": true
}'使用 Python SDK 读取文本
安装 openai 并设置 API_KEY。非流式响应可直接读取 SDK 汇总的 output_text,流式响应按事件类型分别处理。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["API_KEY"],
base_url="https://token.axicomin.cn/v1",
)
model = os.getenv("MODEL_ID", "deepseek-v4-pro")
prompt = "用一句话解释为什么四季会变化。"
response = client.responses.create(model=model, input=prompt, max_output_tokens=512)
print(response.output_text)
if response.status != "completed":
print(response.status, response.error or response.incomplete_details)
with client.responses.create(
model=model,
input=prompt,
max_output_tokens=512,
stream=True,
) as stream:
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
print()
elif event.type in {"response.failed", "response.incomplete"}:
details = event.response.error or event.response.incomplete_details
raise RuntimeError(f"{event.type}: {details}")
elif event.type == "error":
raise RuntimeError(event.message)Anthropic API
#Anthropic Messages 兼容接口为 POST /v1/messages。发送 Authorization: Bearer <YOUR_API_KEY>、Content-Type: application/json 和 anthropic-version: 2023-06-01。模型 ID 以 GET /v1/models 的结果为准。
请求参数
| 字段 | 说明 |
|---|---|
model |
必填。模型 ID。 |
messages |
必填。依次提交 user、assistant 消息。每项的 content 可为文本或内容块数组。 |
max_tokens |
必填。输出 Token 上限。 |
system |
顶层系统指令,可为文本或内容块数组。 |
stream |
为 true 时使用 SSE 返回事件。 |
stop_sequences |
遇到指定序列时结束输出。 |
tools |
工具定义数组,每项可提供 name、description 和用于校验输入的 input_schema。 |
tool_choice |
用 type 选择 auto、any、tool 或 none。指定 tool 时同时提供工具 name。 |
thinking、output_config |
按模型选择推理配置。支持自适应思考的模型可用 thinking.type: "adaptive" 和 output_config.effort,支持手动预算的模型可用 thinking.type: "enabled" 和 thinking.budget_tokens。 |
metadata |
关联调用方的业务信息,例如 user_id。 |
cURL 调用
curl "$BASE_URL/v1/messages" \
-H "Authorization: Bearer $API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 768,
"system": "用简洁的中文回答。",
"messages": [
{"role": "user", "content": "为周末的社区读书会拟一个标题。"}
]
}'Python SDK 调用
安装 anthropic,在运行 Python 前执行 export API_KEY,使终端中已配置的变量可被 Python 读取。
import os
from anthropic import Anthropic
client = Anthropic(
base_url="https://token.axicomin.cn",
auth_token=os.environ["API_KEY"],
default_headers={"anthropic-version": "2023-06-01"},
)
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=768,
messages=[{"role": "user", "content": "为图书馆的旧书交换活动拟一条通知。"}],
)
for block in message.content:
if block.type == "text":
print(block.text)思考配置示例
使用自适应思考时,模型自行分配思考预算。可在请求体中添加下列字段。应为思考和最终答案预留足够的 max_tokens。
{
"thinking": {"type": "adaptive"},
"output_config": {"effort": "medium"}
}如所用模型支持手动预算,可改用 "thinking": {"type": "enabled", "budget_tokens": 2048}。普通请求可以省略思考配置。
响应字段
| 字段 | 含义 |
|---|---|
id、model |
返回消息的标识和实际响应模型。 |
content[] |
按内容块返回输出。文本读取 type: "text" 块的 text,工具调用读取 type: "tool_use" 块。 |
stop_reason |
结束原因,例如 end_turn、max_tokens 或 stop_sequence。 |
usage.input_tokens、usage.output_tokens |
输入和输出 Token 用量。 |
当 stream: true 时按 SSE 事件处理结果。从 content_block_delta 中挑选 delta.type: "text_delta",提取 delta.text,在 message_stop 时结束。
参考:Anthropic API 接入说明 · Anthropic Python SDK · Claude 流式消息协议
Gemini API
#Gemini 原生文本接口为 POST /v1beta/models/{model}:generateContent,使用平台 API Key 进行 Bearer 鉴权。模型 ID 放在路径中。多轮调用在 contents[] 中传入需要保留的 user 和 model 对话内容。
请求参数
| 字段 | 说明 |
|---|---|
model |
必填路径参数。使用模型列表中的 ID。 |
contents[].parts[] |
必填。文本填写 text,文件使用模型支持的内容块。引用的公网 HTTPS 或签名 URL 在处理期间应保持可访问。 |
systemInstruction.parts[] |
系统指令,例如带 text 的内容块。 |
generationConfig.maxOutputTokens、candidateCount |
控制单次输出的 Token 上限及候选数量,候选默认一个。 |
generationConfig.temperature、topP、topK |
控制采样。参考服务给出的温度范围为 0.0 至 2.0,Gemini 3.6 Flash 及后续型号可能忽略温度。 |
generationConfig.stopSequences |
命中数组中的文本序列时停止。 |
generationConfig.responseMimeType、responseSchema |
结构化输出可请求 application/json。参考文档将 responseSchema 标为弃用。 |
generationConfig.thinkingConfig |
可按模型使用 thinkingLevel、thinkingBudget 或 includeThoughts。 |
tools、toolConfig.functionCallingConfig |
定义工具并选择调用模式,例如 AUTO、ANY、NONE。 |
safetySettings、cachedContent |
请求的安全设置,以及用作上下文的缓存内容名称。 |
参考服务记录单个请求载荷的外部文件上限为 100 MB。
cURL 调用
curl "$BASE_URL/v1beta/models/gemini-3.5-flash:generateContent" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "用两句话介绍什么是海绵城市。"}]}
],
"generationConfig": {"maxOutputTokens": 512}
}'Python 调用
安装 requests,并确保已导出 API_KEY。
import os
import requests
model = "gemini-3.5-flash"
response = requests.post(
f"https://token.axicomin.cn/v1beta/models/{model}:generateContent",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={
"systemInstruction": {"parts": [{"text": "使用通俗的中文表达。"}]},
"contents": [{"role": "user", "parts": [{"text": "用一句话解释潮汐。"}]}],
"generationConfig": {"maxOutputTokens": 512},
},
timeout=120,
)
response.raise_for_status()
for candidate in response.json().get("candidates", []):
for part in candidate.get("content", {}).get("parts", []):
if "text" in part:
print(part["text"])响应字段
| 字段 | 含义 |
|---|---|
candidates[].content.role |
响应角色,通常为 model。 |
candidates[].content.parts[] |
使用 text 读取正文,使用 functionCall 读取函数调用。 |
candidates[].finishReason |
对应候选输出的结束原因。 |
usageMetadata |
统计字段包括 promptTokenCount、candidatesTokenCount、totalTokenCount。 |
Gemini 图片生成
#参考服务为 Gemini 图片模型记录了三种接入方式。请先在模型列表中确认所需模型及分辨率档位。
| 方式 | 接口 | 分辨率 |
|---|---|---|
| Gemini 原生方式 | POST /v1beta/models/{model}:generateContent;流式使用 POST /v1beta/models/{model}:streamGenerateContent?alt=sse |
generationConfig.imageConfig.imageSize |
| Chat 兼容普通生图 | POST /v1/chat/completions |
extra_body.google.image_config.image_size,支持 1K、2K、4K |
| Chat 兼容按张生图 | POST /v1/chat/completions |
模型后缀 -1k、-2k、-4k |
Gemini 原生请求
可用的模型包括 gemini-3.1-flash-image-preview 和 gemini-3-pro-image-preview。模型由路径指定,提示词放在 contents[].parts[].text。文图混合输出使用 generationConfig.responseModalities: ["TEXT","IMAGE"],可在 imageConfig 中设置 aspectRatio 和 imageSize。分辨率值 1K、2K、4K 的 K 使用大写。
非流式 cURL
curl "$BASE_URL/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "绘制一张蓝色夜空下的小型天文台插画。"}]}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
}
}'流式 cURL
curl -N "$BASE_URL/v1beta/models/gemini-3.1-flash-image-preview:streamGenerateContent?alt=sse" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "绘制一个复古的车站时钟,采用扁平插画风格。"}]}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"}
}
}'非流式返回 JSON,流式逐条解析 SSE 的 data JSON。两种响应都应遍历 candidates[].content.parts[]。文本位于 text,图片格式和 Base64 内容分别位于 inlineData.mimeType 与 inlineData.data。未取得图片时可检查 candidates[].finishReason 和 promptFeedback,用量见 usageMetadata。
用 Python 保存原生图片
安装 requests,并确保已导出 API_KEY。
import base64
import os
from pathlib import Path
import requests
model = "gemini-3.1-flash-image-preview"
response = requests.post(
f"https://token.axicomin.cn/v1beta/models/{model}:generateContent",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={
"contents": [{"parts": [{"text": "为社区花园绘制一张平面指示牌。"}]}],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"},
},
},
timeout=300,
)
response.raise_for_status()
extensions = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}
image_count = 0
for candidate in response.json().get("candidates", []):
for part in candidate.get("content", {}).get("parts", []):
image = part.get("inlineData")
if not image or part.get("thought"):
continue
extension = extensions[image["mimeType"]]
image_count += 1
Path(f"native-image-{image_count}.{extension}").write_bytes(
base64.b64decode(image["data"], validate=True)
)
if image_count == 0:
raise ValueError("响应中没有可保存的图片")Chat 兼容普通生图
使用模型列表中无尺寸后缀的图片型号,例如 gemini-3.1-flash-image-preview 或 gemini-3-pro-image-preview。分辨率通过 extra_body.google.image_config.image_size 指定,可用值为 1K、2K、4K。可在同一对象中设置 aspect_ratio。
curl "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview",
"messages": [{"role": "user", "content": "生成正方形咖啡店图标,使用深蓝与白色。"}],
"extra_body": {
"google": {"image_config": {"aspect_ratio": "1:1", "image_size": "1K"}}
}
}'Chat 兼容按张生图
这类型号以 -1k、-2k 或 -4k 后缀固定分辨率。可在 gemini-3.1-flash-image-preview 或 gemini-3-pro-image-preview 的已开通档位中选择。请求省略 image_size,单次默认生成一张。参考服务按输出张数计费,实际费率以当前站点为准。
curl "$BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview-2k",
"messages": [
{"role": "user", "content": "绘制一张明亮的城市植物观察手册封面。"}
]
}'用 Python 保存 Chat 兼容图片
两种 Chat 模式都从 choices[0].message.content 取图。响应可能直接在文本中含有图片 Data URL,也可能在内容块的 image_url.url 中返回。下例默认请求普通生图。以 python save_gemini_image.py gemini-3.1-flash-image-preview-2k 运行同一脚本可以选择按张档。
import base64
import os
import re
import sys
from pathlib import Path
import requests
model = sys.argv[1] if len(sys.argv) > 1 else "gemini-3.1-flash-image-preview"
body = {
"model": model,
"messages": [{"role": "user", "content": "画一枚青色书签的图标。"}],
}
if not model.endswith(("-1k", "-2k", "-4k")):
body["extra_body"] = {"google": {"image_config": {"image_size": "1K"}}}
response = requests.post(
"https://token.axicomin.cn/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json=body,
timeout=300,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
if isinstance(content, str):
parts = [content]
else:
parts = [
item.get("image_url", {}).get("url", "")
if item.get("type") == "image_url"
else item.get("text", "")
for item in (content or [])
]
data_url = re.compile(r"data:image/(png|jpeg|webp);base64,([A-Za-z0-9+/=]+)")
for part in parts:
match = data_url.search(part)
if match:
extension, data = match.groups()
extension = "jpg" if extension == "jpeg" else extension
Path(f"gemini-image.{extension}").write_bytes(
base64.b64decode(data, validate=True)
)
break
else:
raise ValueError("响应中没有可保存的图片 Data URL")GPT 图片生成
#GPT Image 兼容接口支持 gpt-image-2。POST /v1/images/generations 用于提示词生图,POST /v1/images/edits 用于以现有图片为输入继续生成。参考服务记录的单次请求产出为一张,可省略 n 或设为 1。默认图片数据位于 data[0].b64_json。
生成新图片
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "白底的手工茶壶产品照片,自然光,留出排版空间",
"size": "1536x1024",
"quality": "high",
"output_format": "png"
}'本地图片编辑
本地文件通过 multipart 上传。普通单图编辑只需传 image 和编辑提示词。需要局部重绘时另传 mask,遮罩和原图尺寸应一致,且包含透明通道。
curl "$BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=只改变遮罩选中的背景区域,换成浅灰色" \
-F "image=@product.png" \
-F "mask=@mask.png" \
-F "output_format=png"上传多张参考图
每张图使用一个 image[] 字段。提示词按上传顺序说明各图的用途。需要提高参考图保真度时,可传 input_fidelity=high。
curl "$BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=参考第一张的陶杯造型和第二张的桌面材质,生成横向海报" \
-F "image[]=@cup.png" \
-F "image[]=@table.png" \
-F "input_fidelity=high" \
-F "size=1536x1024"用公网 URL 或 Data URL 编辑
使用 JSON 请求时,将引用填入 images[].image_url。下例组合一张可公开访问的图片与一个由本地 PNG 编码的 Data URL。将 https://example.com/images/cup.png 替换为实际公网图片。
IMAGE_DATA="$(base64 < table.png | tr -d '\r\n')"
curl "$BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<JSON
{
"model": "gpt-image-2",
"prompt": "保留陶杯颜色,将其摆在参考图的木桌上",
"images": [
{"image_url": "https://example.com/images/cup.png"},
{"image_url": "data:image/png;base64,$IMAGE_DATA"}
],
"output_format": "png"
}
JSON用 Python 保存图片
生成和编辑都可按下列方式解析响应。安装 requests,并确保已导出 API_KEY。
import base64
import os
from pathlib import Path
import requests
response = requests.post(
"https://token.axicomin.cn/v1/images/generations",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={
"model": "gpt-image-2",
"prompt": "绘制一个几何形状组成的蓝色自行车图标",
"size": "1024x1024",
"quality": "medium",
"output_format": "png",
},
timeout=180,
)
response.raise_for_status()
image = response.json()["data"][0]["b64_json"]
Path("bicycle.png").write_bytes(base64.b64decode(image, validate=True))参数参考
| 参数 | 适用方式与取值 |
|---|---|
model、prompt |
生成和编辑都使用模型名及提示词。编辑时描述应保留和修改的元素。 |
n |
两种方式均可省略或传 1。 |
size |
常用 1024x1024、1536x1024、1024x1536、auto。自定义宽高使用 16 的倍数,参考服务建议宽高比在 1:3 至 3:1。 |
quality |
生成和编辑均可用 low、medium、high 或 auto。 |
output_format |
png、jpeg 或 webp。JPEG 和 WebP 还可设置 output_compression。 |
image、image[]、mask |
Multipart 编辑的单图、多图和可选遮罩。 |
images[].image_url |
JSON 编辑用公网图片 URL 或 Data URL。 |
input_fidelity |
图片编辑的参考图保真选项,可传 high 或 low。 |
Seedream 图片生成
#- 接口:
POST /v1/images/generations - 模型:
doubao-seedream-5-0-pro-260628、doubao-seedream-5.0-lite - Pro 支持文生单图、单图生单图和最多 10 张参考图的多图生单图;分辨率支持
1K、1.5K、2K,默认2K - Pro 不支持组图、联网搜索和流式输出,不要传
sequential_image_generation、tools或stream
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro-260628",
"prompt": "现代客厅产品摄影,柔和自然光",
"image": [
"https://example.com/product.png",
"https://example.com/style.png"
],
"size": "2K",
"output_format": "png",
"response_format": "url",
"watermark": false
}'Lite 组图需使用 sequential_image_generation: "auto",并可通过 sequential_image_generation_options.max_images 设置最大生成数量。响应图片地址位于 data[0].url,链接有效期为 24 小时;使用 response_format: "b64_json" 时读取 data[0].b64_json。
Lite 组图与输出规格
Lite 支持 2K、3K、4K。参考服务记录 Lite 一次最多接收 14 张参考图,输入图和输出图合计最多 15 张。指定 size 时选择分辨率档位或 宽x高,两种形式择一。参考图 image 可传单个值或数组,支持公网 URL 或 Base64 数据。
下面的示例最多生成三张风格连贯的图片。遍历 data[] 读取所有结果。
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5.0-lite",
"prompt": "以同一配色绘制三张森林海报,分别表现晨雾、午后和暮色",
"size": "3K",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {"max_images": 3},
"response_format": "url"
}'请求字段和保存方式
| 字段 | 类型 | 说明 |
|---|---|---|
model、prompt |
string | 必填。提示词可用中文或英文,参考建议为不超过 300 个汉字或 600 个英文单词。 |
| `image | string 或 string[] | 参考图为可访问的 URL 或 Base64 数据。单图可传字符串,多图使用数组。 |
| `size | string | 选择模型支持的档位,或传入一个 `宽x高 字符串。 |
| `output_format | string | jpeg(默认)或 png。 |
| `response_format | string | url(默认)或 b64_json。 |
| `watermark | boolean | 默认开启。 |
| `sequential_image_generation | string | Lite 使用 auto 开启组图,最大张数由 sequential_image_generation_options.max_images 控制。 |
Pro 纯文本生图
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro-260628",
"prompt": "设计一张以白鹭为主体的湿地保护海报",
"size": "1.5K",
"output_format": "png"
}'Pro 单张参考图
使用公开图片地址替换此例中的素材。
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro-260628",
"prompt": "保持纸质包装的形状,把桌面改成浅木纹",
"image": "https://example.com/images/paper-package.png",
"size": "2K"
}'用 Python 保存图片
以下示例依赖 requests,使用 b64_json 直接写文件。先在运行环境中设置 `API_KEY。
import base64
import os
from pathlib import Path
import requests
response = requests.post(
"https://token.axicomin.cn/v1/images/generations",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={
"model": "doubao-seedream-5-0-pro-260628",
"prompt": "清晨的冬日山谷,木刻插画",
"output_format": "png",
"response_format": "b64_json",
},
timeout=180,
)
response.raise_for_status()
for index, item in enumerate(response.json()["data"], start=1):
Path(f"valley-{index}.png").write_bytes(base64.b64decode(item["b64_json"]))Wan 图片生成与编辑
#- 文生图:
POST /v1/images/generations - 图片编辑:
POST /v1/images/edits wan2.7-image-pro、wan2.7-image支持文生图和图片编辑wan2.6-image使用图片编辑接口,并需上传 1 至 4 张参考图n取值 1 至 4,默认 1;response_format支持url和b64_jsonwan2.7-image-pro文生图最高4K,wan2.7-image文生图最高2K;图片编辑使用模型的默认输出规格
文生图:
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-image-pro",
"prompt": "高端香水产品摄影,透明玻璃瓶置于黑色镜面上,冷暖交错的工作室灯光",
"size": "4K",
"n": 1,
"response_format": "url",
"watermark": false
}'多图参考编辑使用 multipart/form-data,按上传顺序在提示词中引用图片:
curl "$BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $API_KEY" \
-F "model=wan2.7-image-pro" \
-F "prompt=把图 2 的图案应用到图 1 的包装盒上,保持图 1 的构图、材质和光线不变" \
-F "image[]=@./package.png" \
-F "image[]=@./pattern.png" \
-F "n=1" \
-F "response_format=url" \
-F "watermark=false"默认读取 data[0].url。使用 response_format: "b64_json" 时读取 data[0].b64_json。URL 在 24 小时内有效,请及时保存图片。
编辑模式与参考图限制
参考服务为 Wan 2.7 两个型号记录了最多九张参考图,编辑结果默认 2K。Wan 2.6 编辑使用一至四张参考图,默认 1K,宽高比随最后一张参考图。编辑请求使用 multipart/form-data,按照上传次序在提示词中指代各张参考图。多图以多个 image[] 字段传入。文生图提示词上限为 5000 个字符。输出数量 n 也影响费用。
端点参数
| 字段 | 端点 | 说明 |
|---|---|---|
model、prompt |
生成与编辑 | 必填。编辑提示词按上传顺序指代素材。 |
| `size | 生成 | 档位或 宽x高。Pro 默认 2K,可指定 `4K。 |
image、image[] |
编辑 | 单张用 image,多张重复传 image[]。 |
| `n | 生成与编辑 | 1 至 4,默认 `1。 |
| `response_format | 生成与编辑 | url(默认)或 b64_json。 |
| `watermark | 生成与编辑 | 默认 `false。 |
响应中的 created 使用 Unix 时间戳。按响应格式分别获取 data[].url 或 `data[].b64_json。
Wan 2.7 标准版文生图
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"wan2.7-image","prompt":"绘制秋日社区集市的平面插画","size":"2K","n":1}'Wan 2.6 单图编辑
curl "$BASE_URL/v1/images/edits" \
-H "Authorization: Bearer $API_KEY" \
-F "model=wan2.6-image" \
-F "image=@./bicycle.png" \
-F "prompt=保持自行车外观,将背景改为白色摄影棚"Qwen Image 图片生成与编辑
#- 协议:OpenAI Images
- 接口:
POST /v1/images/generations - 模型:
qwen-image-3.0、qwen-image-3.0-pro - 支持文生图和参考图编辑;编辑时在
input.messages[].content中按顺序传入公网图片 URL 与编辑提示词,最多 3 张图片 size使用宽x高格式,宽高比为 1:8 至 8:1,像素面积为 512×512 至 2048×2048n可设为 1 至 6,默认 1;费用按实际生成图片数量核算,具体费率以平台显示为准parameters.prompt_extend默认为true;图片 URL 有效期为 24 小时
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-3.0-pro",
"prompt": "一只坐在窗边的橘猫,柔和的午后阳光,写实摄影",
"n": 1,
"response_format": "url",
"parameters": {"size": "1024x1024", "prompt_extend": true, "seed": 12345, "watermark": false}
}'成功响应从 data[].url 或 data[].b64_json 读取图片。
参考图编辑请求
参考图编辑仍通过 POST /v1/images/generations 提交。用一个 role: "user" 的消息承载参考图和编辑指令,图片地址及编辑内容顺序由 content[] 决定。使用 parameters 时,将尺寸填在 parameters.size 内。嵌套的 parameters.n 优先于顶层 n。启用智能提示词改写后,结果中可能出现 data[].revised_prompt。
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-3.0-pro",
"prompt": "保留产品外观,将背景替换成浅灰色",
"input": {
"messages": [
{"role": "user", "content": [
{"image": "https://example.com/images/ceramic-mug.png"},
{"text": "保留产品外观,将背景替换成浅灰色"}
]}
]
},
"parameters": {"size": "1024x1024", "n": 1}
}'完整编辑字段
| 字段 | 说明 |
|---|---|
model、prompt |
必填。选择 qwen-image-3.0 或 qwen-image-3.0-pro。 |
| `size | 可选。以 宽x高 指定画幅,省略时由模型决定。使用 parameters 时将尺寸写到 `parameters.size。 |
n、parameters.n |
生成数量,1 至 6,默认 `1。优先读取嵌套值。 |
| `response_format | url(默认)或 b64_json。 |
| `input.messages[] | 编辑时使用一个 `role: "user" 的消息,按顺序提供图片和指令。 |
| `input.messages[].content[].image | 公网 HTTP(S) 参考图片,编辑时传 1 至 3 张。 |
| `input.messages[].content[].text | 编辑指令。 |
| `parameters.prompt_extend | 智能改写提示词,默认开启。 |
| `parameters.seed | 随机种子,范围 0 至 2147483647。 |
| `parameters.watermark | 是否在结果图添加水印,默认关闭。 |
created 是创建时间。data[] 对应结果数组,可按输出格式读取 url 或 b64_json,智能改写的文本在 `revised_prompt 可用时返回。
Z-Image 图片生成
#- 协议:OpenAI Images
- 接口:
POST /v1/images/generations - 模型:
z-image-turbo - 提示词最长 800 个字符;固定生成 1 张图片
size使用宽x高,总像素范围对应512x512至2048x2048;parameters.prompt_extend默认为false
curl "$BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "z-image-turbo",
"prompt": "一只坐着的橘黄色猫咪,电影感光影,高清写实",
"size": "1024x1536",
"response_format": "url",
"parameters": {"prompt_extend": false}
}'成功响应从 data[0].url 或 data[0].b64_json 读取图片。URL 有效期约 24 小时,请及时保存。
默认尺寸与可选种子
省略 size 时默认 1024x1536。parameters.seed 支持整数 0 至 2147483647,复用种子可以提高生成稳定性。启用 parameters.prompt_extend 后可以查看 data[0].revised_prompt。参考服务将改写模式列为更高计费档,实际价格以当前站点为准。
参考:Z-Image 请求参数
请求与响应字段
| 字段 | 说明 |
|---|---|
model、prompt |
必填。使用 `z-image-turbo。 |
| `size | 可选,默认 `1024x1536。 |
| `response_format | url(默认)或 b64_json。 |
| `parameters.prompt_extend | 开启提示词改写,默认关闭。 |
| `parameters.seed | 可复用的整数种子。 |
| `parameters.watermark | 是否添加水印。 |
从 created 查看响应时间。单张图片位于 data[0]。选择 Base64 时读取 `b64_json,选择 URL 时应在有效期内保存。
Seedance
#本章目录
火山方舟 Ark 协议
- 创建任务:
POST /ark/api/v3/contents/generations/tasks - 查询任务:
GET /ark/api/v3/contents/generations/tasks/{task_id} - 删除任务:
DELETE /ark/api/v3/contents/generations/tasks/{task_id} - 模型:
doubao-seedance-2-5、doubao-seedance-2-0-mini、doubao-seedance-2-0、doubao-seedance-2-0-fast、doubao-seedance-2-5-flash
创建视频生成任务
content 为多模态输入数组,可使用 text、image_url、video_url 和 audio_url。常用生成参数包括 ratio、duration、resolution、generate_audio 和 output_format;generate_audio 默认值为 true,以模型实际能力为准。output_format 仅适用于 Seedance 2.5,可取 mp4 或 mov,默认 mp4;mov 适合专业后期处理,但部分播放器可能不兼容。
duration 需按模型和任务类型设置:
- Seedance 2.5 普通生成任务:固定时长支持 4 至 30 秒;默认值为
-1,表示由模型在有效范围内智能选择整数秒时长。 - Seedance 2.5 视频编辑任务:
duration必须为-1,不支持指定固定输出时长;待编辑视频时长必须为 4 至 30 秒,输出时长与输入视频基本一致。 - Seedance 2.0 系列:固定时长支持 4 至 15 秒,也可设置为
-1由模型智能选择。
ratio 可取 16:9、9:16、1:1、4:3、3:4、21:9 或 adaptive。Seedance 2.5 首帧和首尾帧任务应省略 ratio(默认 adaptive)或传入 adaptive,输出比例跟随 first_frame;传入具体比例会返回 InvalidParameter.TaskTypeConstraint。视频编辑和视频延长任务的 ratio 必须为 adaptive。
Seedance 2.5 全模态参考生视频任务可通过 omni_reference_task_type 指定类型,默认值为 auto:
reference:参考生视频,ratio和duration遵循通用限制。edit:视频编辑,content至少包含一个 4 至 30 秒的reference_video,ratio必须为adaptive,duration必须为-1。extend:视频延长,content至少包含一个reference_video,ratio必须为adaptive。
省略该字段或设置为 auto 时,模型根据输入素材和提示词判定任务类型;参数不兼容时,任务创建后可能以 InvalidParameter.TaskTypeConstraint 失败。显式指定类型后,提示词意图仍须与该类型一致,否则任务创建后可能以 InvalidParameter.TaskTypeMismatch 失败。
文生视频
curl -X POST "$BASE_URL/ark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"content": [
{
"type": "text",
"text": "写实汽车广告风格,一辆深银色概念跑车为全片唯一主体。0-5秒:16:9大全景,清晨薄雾中的山间公路,镜头贴近路面缓慢前移,车辆从弯道驶入画面;5-10秒:低机位侧向跟拍,车身反射自然晨光,轮胎与路面运动符合真实物理规律,背景产生克制的速度感;10-15秒:镜头平滑切换至前方四分之三英雄视角,车辆在观景台稳稳停下,最后两秒定格。全程主体外观和色彩一致,运镜连续,画面无跳变、无字幕、无水印。生成与画面同步的引擎声、轮胎摩擦声和自然环境声,禁止旁白。"
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 15,
"resolution": "720p",
"output_format": "mp4"
}'素材图生视频
curl -X POST "$BASE_URL/ark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"content": [
{
"type": "text",
"text": "写实商业广告风格,必须以参考素材中的主体、造型、颜色和视觉元素为全片统一锚点,不得替换主体,不得改变关键外观。0-5秒:中景开场,镜头从参考素材左前方缓慢推进,主体保持清晰,环境出现柔和晨光和轻微自然风,突出新鲜质感;5-10秒:连续运镜切换到近景,围绕参考素材完成一次顺滑的半环绕拍摄,展示表面细节、光泽和层次,动作符合真实物理规律,画面不跳变、不新增无关主体;10-15秒:镜头平稳拉回产品英雄镜头,主体居中并与参考素材高度一致,背景简洁、景深自然,最后两秒稳定定格。全程镜头连续,色彩一致,无字幕、无水印、无标志变形。生成与画面同步的自然环境声、轻柔转场声和克制的广告氛围音乐,禁止旁白。"
},
{
"type": "image_url",
"role": "first_frame",
"image_url": {
"url": "asset://asset-xxxxxxxx"
}
}
],
"generate_audio": true,
"duration": 15,
"resolution": "720p",
"output_format": "mp4"
}'Seedance 2.5 可使用 draft: true 创建 480p 样片,确认场景结构、镜头调度、主体动作和提示词意图。draft 默认为 false;开启后 resolution 必须为 480p,否则会报错。样片任务成功后,在正式视频请求的 content 中加入 {"type":"draft_task","draft_task":{"id":"<DRAFT_TASK_ID>"}};使用创建样片时返回的任务 id。
生成样片
curl -X POST "$BASE_URL/ark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"model":"doubao-seedance-2-5","content":[{"type":"text","text":"一辆银色汽车沿海岸公路行驶,镜头平稳跟拍。"}],"draft":true,"resolution":"480p"}'根据样片生成正式视频
curl -X POST "$BASE_URL/ark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"model":"doubao-seedance-2-5","content":[{"type":"text","text":"保留样片中的汽车和运镜,生成清晰的正式视频。"},{"type":"draft_task","draft_task":{"id":"<DRAFT_TASK_ID>"}}],"resolution":"720p"}'创建任务成功后仅返回任务 id:
{
"id": "cgt-20260730175939-nbf6p"
}查询视频生成任务
curl "$BASE_URL/ark/api/v3/contents/generations/tasks/<task_id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Accept: application/json"任务状态包括 queued、running、succeeded、failed、cancelled 和 expired。成功后读取 content.video_url,失败后读取 error;根据样片生成的任务可从 draft_task_id 读取样片任务 ID。建议每 3 至 5 秒轮询一次,并对 HTTP 429 和 5xx 使用指数退避。
删除视频生成任务
curl -X DELETE "$BASE_URL/ark/api/v3/contents/generations/tasks/<task_id>" \
-H "Authorization: Bearer $API_KEY" \
-H "Accept: application/json"| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
task_id |
string | 是 | 创建任务时返回的任务 ID。 |
| HTTP 状态码 | 错误码 | 说明 |
|---|---|---|
204 |
- | 删除成功,无响应体。 |
409 |
InvalidAction.RunningTaskDeletion |
当前任务状态不支持删除。 |
404 |
ResourceNotFound |
任务不存在或已删除。 |
仅支持删除状态为 succeeded、failed 或 expired 的任务。删除后无法再查询该任务,重复删除返回 HTTP 404。
火山方舟素材类型与 Dreamina 型号
| 素材 | type |
role |
地址字段 |
|---|---|---|---|
| 首帧或尾帧 | image_url |
first_frame 或 last_frame |
image_url.url |
| 参考图 | image_url |
reference_image |
image_url.url |
| 参考视频 | video_url |
reference_video |
video_url.url |
| 参考音频 | audio_url |
reference_audio |
audio_url.url |
素材可用公网文件直链,或引用 素材资产库 中已经变为 Active 的 asset://{asset_id}。参考音频需要同时搭配图片或视频。提示词可按 content 数组中的素材顺序,用“图片1”等方式指代素材。
参考服务还列出 dreamina-seedance-2-5 和 dreamina-seedance-2-0,通过同一 Ark 任务端点提交。使用前以本平台的模型列表和当前账号权限为准。
首尾帧与视频延长请求体
以下请求体提交到 POST /ark/api/v3/contents/generations/tasks。content 至少包含一个输入项。resolution 可填写 480p、720p 或 1080p,具体挡位由所选模型决定。
指定首尾帧时,画幅跟随首帧。以下用公网图片作为首尾帧,并省略 ratio。
{
"model": "doubao-seedance-2-5",
"content": [
{"type": "text", "text": "从打开的木盒缓慢移到桌上的纸船,保持光线方向一致。"},
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/wooden-box.jpg"}},
{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/paper-boat.jpg"}}
],
"resolution": "720p",
"duration": 8
}延长视频时,传入 reference_video,使用 extend,并在提示词中描述接续的镜头。
{
"model": "doubao-seedance-2-5",
"content": [
{"type": "text", "text": "接着原片继续拍摄,让纸船漂过桥墩,维持原片运镜。"},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/river-scene.mp4"}}
],
"omni_reference_task_type": "extend",
"ratio": "adaptive",
"resolution": "720p",
"duration": -1
}查询响应中的输出规格
成功结果同时给出视频直链和实际生成参数。下面保留常用于下载、展示和对账的字段。
{
"id": "<TASK_ID>",
"model": "doubao-seedance-2-5",
"status": "succeeded",
"content": {"video_url": "https://example.com/river-scene-result.mp4"},
"usage": {"completion_tokens": 64000, "total_tokens": 64000},
"error": null,
"resolution": "720p",
"ratio": "16:9",
"duration": 8,
"framespersecond": 24,
"generate_audio": true,
"draft": false
}查询响应还可包含创建、更新的 Unix 秒级时间戳 created_at、updated_at,以及 seed、service_tier、execution_expires_after、priority。 Seedance 参考文档
Seedance 素材资产库
#本章目录
素材资产库支持 Bearer API-Key 和 AK/SK 签名两种鉴权方式。常规调用推荐使用 Bearer API-Key,本文示例均采用该方式。AK/SK 签名用于兼容火山方舟 Ark 签名规范。所有接口均使用 POST /api/v3/?Action={Action}&Version=2024-01-01,字段名区分大小写。
接口索引
| 接口名称 | Action | 说明 |
|---|---|---|
| 创建素材资产 | CreateAsset |
创建素材并关联素材组。 |
| 查询素材资产详情 | GetAsset |
查询指定素材的详情和处理状态。 |
| 查询素材资产列表 | ListAssets |
分页查询素材列表。 |
| 更新素材资产 | UpdateAsset |
更新指定素材的名称。 |
| 删除素材资产 | DeleteAsset |
删除指定素材。 |
| 创建素材资产组 | CreateAssetGroup |
创建素材组,用于归类素材。 |
| 查询素材资产组详情 | GetAssetGroup |
查询指定素材组的详情。 |
| 查询素材资产组列表 | ListAssetGroups |
分页查询素材组列表。 |
| 更新素材资产组 | UpdateAssetGroup |
更新指定素材组的名称和描述。 |
| 删除素材资产组 | DeleteAssetGroup |
删除指定素材组及组内素材。 |
| 拉起真人人像认证 H5 | CreateVisualValidateSession |
创建真人人像认证会话。 |
| 获取真人人像 Asset Group ID | GetVisualValidateResult |
查询真人人像认证结果。 |
AK/SK 签名鉴权(可选)
前往 $BASE_URL/keys,在目标 API Key 的扩展菜单中选择 Ark AK/SK 并生成凭证。
- 每个 API Key 仅保留一组有效的 Ark AK/SK。
- Secret Key 仅在生成或重新生成时展示一次,请立即妥善保存。
- 重新生成后,原 AK/SK 立即失效。
Ark AK/SK 调用上述 Action 接口,请使用以下签名参数:
| 签名项 | 值 |
|---|---|
| 算法 | HMAC-SHA256 |
| Credential Scope | YYYYMMDD/cn-beijing/ark/request |
| Signed Headers | content-type;host;x-content-sha256;x-date |
X-Date |
UTC 时间,格式为 YYYYMMDDTHHmmssZ;与服务端时间偏差不得超过 15 分钟。 |
X-Content-Sha256 |
请求体的 SHA-256 十六进制摘要。 |
POST /api/v3/?Action=ListAssets&Version=2024-01-01
Authorization: HMAC-SHA256 Credential=<ARK_ACCESS_KEY>/<YYYYMMDD>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<SIGNATURE>
Content-Type: application/json
Host: token.axicomin.cn
X-Content-Sha256: <PAYLOAD_SHA256>
X-Date: <UTC_TIMESTAMP>
{}素材资产
创建素材资产
POST /api/v3/?Action=CreateAsset&Version=2024-01-01
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
URL |
string | 是 | - | 服务端可访问的公网 HTTP 或 HTTPS 素材地址,最多 8192 字节。 |
GroupId |
string | 是 | - | 素材组 ID。 |
Name |
string | 否 | reference |
素材名称,最多 64 个字符。 |
AssetType |
string | 否 | Image |
Image、Video 或 Audio。 |
curl -X POST "$BASE_URL/api/v3/?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: <UNIQUE_REQUEST_ID>" \
-H "Content-Type: application/json" \
-d '{
"GroupId": "group-xxxxxxxx",
"Name": "first-frame",
"URL": "https://example.com/first-frame.jpg",
"AssetType": "Image"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Id": "asset-xxxxxxxx"
}
}查询素材资产详情
POST /api/v3/?Action=GetAsset&Version=2024-01-01
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 素材 ID。 |
curl -X POST "$BASE_URL/api/v3/?Action=GetAsset&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Id": "asset-xxxxxxxx"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "GetAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Id": "asset-xxxxxxxx",
"Name": "first-frame",
"URL": "asset://asset-xxxxxxxx",
"AssetType": "Image",
"Status": "Active",
"Moderation": {"Strategy": "Default"},
"Error": {"Code": "", "Message": ""},
"CreateTime": "2026-07-20T04:00:00Z",
"UpdateTime": "2026-07-20T04:00:03Z"
}
}素材状态包括 Processing、Active 和 Failed。状态变为 Active 后,使用 Result.URL 创建视频任务。
查询素材资产列表
POST /api/v3/?Action=ListAssets&Version=2024-01-01
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
Filter.GroupIds |
array | 否 | - | 素材组 ID 列表,最多 100 项;省略时查询当前 API Key 下的全部素材。 |
Filter.GroupType |
string | 否 | - | 可选 AIGC 或 LivenessFace。 |
Filter.Statuses |
array | 否 | - | Processing、Active、Failed。 |
Filter.Name |
string | 否 | - | 按素材名称关键字筛选。 |
PageNumber |
integer | 否 | 1 |
页码,大于等于 1。 |
PageSize |
integer | 否 | 10 |
每页数量,1 至 100。 |
SortBy |
string | 否 | CreateTime |
CreateTime、UpdateTime、GroupId。 |
SortOrder |
string | 否 | Desc |
Asc 或 Desc。 |
curl -X POST "$BASE_URL/api/v3/?Action=ListAssets&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Filter": {"Statuses": ["Active"]},
"PageNumber": 1,
"PageSize": 20,
"SortBy": "CreateTime",
"SortOrder": "Desc"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [
{
"Id": "asset-xxxxxxxx",
"Name": "first-frame",
"URL": "asset://asset-xxxxxxxx",
"AssetType": "Image",
"Status": "Active",
"CreateTime": "2026-07-20T04:00:00Z",
"UpdateTime": "2026-07-20T04:00:03Z"
}
],
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 20
}
}更新素材资产
POST /api/v3/?Action=UpdateAsset&Version=2024-01-01
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 素材 ID。 |
Name |
string | 是 | 新的素材名称,最多 64 个字符。 |
curl -X POST "$BASE_URL/api/v3/?Action=UpdateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Id": "asset-xxxxxxxx",
"Name": "first-frame-v2"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "UpdateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {"Id": "asset-xxxxxxxx"}
}删除素材资产
POST /api/v3/?Action=DeleteAsset&Version=2024-01-01
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 待删除的素材 ID。 |
curl -X POST "$BASE_URL/api/v3/?Action=DeleteAsset&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Id": "asset-xxxxxxxx"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "DeleteAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {}
}素材资产组
创建素材资产组
POST /api/v3/?Action=CreateAssetGroup&Version=2024-01-01
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
Name |
string | 是 | - | 素材组名称,最多 64 个字符。 |
Description |
string | 否 | - | 素材组描述,最多 300 个字符。 |
GroupType |
string | 否 | AIGC |
素材组类型,仅支持 AIGC。 |
curl -X POST "$BASE_URL/api/v3/?Action=CreateAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: <UNIQUE_REQUEST_ID>" \
-H "Content-Type: application/json" \
-d '{
"Name": "product-video",
"Description": "product video assets",
"GroupType": "AIGC"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "CreateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {"Id": "group-xxxxxxxx"}
}查询素材资产组详情
POST /api/v3/?Action=GetAssetGroup&Version=2024-01-01
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 素材组 ID。 |
curl -X POST "$BASE_URL/api/v3/?Action=GetAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Id": "group-xxxxxxxx"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "GetAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Id": "group-xxxxxxxx",
"Name": "product-video",
"Description": "product video assets",
"GroupType": "AIGC",
"CreateTime": "2026-07-20T04:00:00Z",
"UpdateTime": "2026-07-20T04:00:00Z"
}
}查询素材资产组列表
POST /api/v3/?Action=ListAssetGroups&Version=2024-01-01
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
Filter.GroupIds |
array | 否 | - | 素材组 ID 列表,最多 100 项。 |
Filter.Name |
string | 否 | - | 按素材组名称关键字筛选。 |
Filter.GroupType |
string | 否 | - | 可选 AIGC 或 LivenessFace。 |
PageNumber |
integer | 否 | 1 |
页码,大于等于 1。 |
PageSize |
integer | 否 | 10 |
每页数量,1 至 100。 |
SortBy |
string | 否 | CreateTime |
CreateTime 或 UpdateTime。 |
SortOrder |
string | 否 | Desc |
Asc 或 Desc。 |
curl -X POST "$BASE_URL/api/v3/?Action=ListAssetGroups&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"PageNumber": 1,
"PageSize": 20,
"SortBy": "CreateTime",
"SortOrder": "Desc"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "ListAssetGroups",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [
{
"Id": "group-xxxxxxxx",
"Name": "product-video",
"Description": "product video assets",
"GroupType": "AIGC"
}
],
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 20
}
}更新素材资产组
POST /api/v3/?Action=UpdateAssetGroup&Version=2024-01-01
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 素材组 ID。 |
Name |
string | 否 | 新的素材组名称,最多 64 个字符。 |
Description |
string | 否 | 新的素材组描述,最多 300 个字符。 |
Name 和 Description 至少传一个。
curl -X POST "$BASE_URL/api/v3/?Action=UpdateAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Id": "group-xxxxxxxx",
"Name": "product-video-v2"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "UpdateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {"Id": "group-xxxxxxxx"}
}删除素材资产组
POST /api/v3/?Action=DeleteAssetGroup&Version=2024-01-01
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Id |
string | 是 | 待删除的素材组 ID。 |
curl -X POST "$BASE_URL/api/v3/?Action=DeleteAssetGroup&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Id": "group-xxxxxxxx"
}'
# 响应示例
{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "DeleteAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {}
}真人人像认证
拉起真人人像认证 H5
POST /api/v3/?Action=CreateVisualValidateSession&Version=2024-01-01
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
CallbackURL |
string | 是 | - | 公网可访问的 HTTPS 回调地址。 |
ProjectName |
string | 否 | default |
项目名称。 |
curl -X POST "$BASE_URL/api/v3/?Action=CreateVisualValidateSession&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"CallbackURL": "https://example.com/verification/callback",
"ProjectName": "default"
}'{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "CreateVisualValidateSession",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"BytedToken": "vvs-xxxxxxxx",
"H5Link": "https://example.com/visual-validation/xxxxxxxx",
"CallbackURL": "https://example.com/verification/callback"
}
}获取真人人像 Asset Group ID
POST /api/v3/?Action=GetVisualValidateResult&Version=2024-01-01
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
BytedToken |
string | 是 | - | 创建真人人像认证会话返回的认证令牌。 |
ProjectName |
string | 否 | default |
项目名称。 |
curl -X POST "$BASE_URL/api/v3/?Action=GetVisualValidateResult&Version=2024-01-01" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"BytedToken": "vvs-xxxxxxxx",
"ProjectName": "default"
}'{
"ResponseMetadata": {
"RequestId": "req-xxxxxxxx",
"Action": "GetVisualValidateResult",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"GroupId": "group-xxxxxxxx"
}
}错误码
创建或查询视频任务时,如果 HTTP 状态码不是 2xx,响应使用以下结构。param 仅在能够定位到具体参数时返回。
{
"error": {
"code": "InvalidParameter",
"message": "One or more parameters specified in the request are not valid.",
"param": "duration",
"type": "BadRequest"
}
}| HTTP 状态码 | 常见 error.code |
处理建议 |
|---|---|---|
400 |
InvalidParameter、MissingParameter、各类 SensitiveContentDetected |
检查必填参数、模型支持范围和素材格式;命中内容安全检查时更换输入,不要使用相同请求直接重试。 |
401 |
AuthenticationError |
检查 Bearer API Key 是否缺失、错误或已失效;使用 AK/SK 签名时,检查 Access Key、签名和请求时间。 |
403 |
AccessDenied、AccountOverdueError、OperationDenied.ServiceNotOpen |
确认模型服务已开通、API Key 有访问权限且账户余额正常。 |
404 |
NotFound.Resource、InvalidEndpointOrModel.NotFound、ModelNotOpen |
检查任务、模型或资源 ID,并确认查询任务时使用创建任务的同一 API Key。 |
429 |
ServerOverloaded、RateLimitExceeded.*、QuotaExceeded |
降低请求频率和并发;限流或过载时使用带随机抖动的指数退避。额度耗尽时应先补充额度,不要盲目重试。 |
5xx |
InternalServiceError |
对临时服务异常使用带随机抖动的指数退避;持续失败时记录错误信息并联系技术支持。 |
HTTP 请求成功但任务状态变为 failed 时,请读取任务响应中的 error.code 和 error.message;任务运行失败与同步 HTTP 错误应分别处理。
使用建议
- 不要将素材库作为永久素材存储,应永久保存原始素材 URL。
- 获得
asset_id后应尽快创建视频任务。 asset_id受官方账号容量限制,可能因容量清理或替换而失效;超过一天的素材在使用前必须重新确认状态。- 素材不存在或失效时,使用原始 URL 重新上传并获取新的
asset_id。 - 素材上传受 QPS 限制;对限流或临时失败采用指数退避重试,并复用原
Idempotency-Key。 - 素材资产组、素材资产和视频任务均与 API Key 绑定。后续查询和调用应使用同一个 API Key;使用 AK/SK 签名时,应使用该 API Key 下生成的凭证。
引用已处理的素材
如果 Action 接口没有需要填写的参数,仍发送空 JSON 对象 {}。使用已入库素材前,调用 GetAsset 确认 Result.Status 为 Active,再把响应中 Result.URL 的 asset:// 地址复制到生成任务对应的媒体项。对于无需人像认证的公开素材,也可直接在生成任务使用原始公网文件地址。 Seedance 素材资产库参考文档
Wan 视频生成
#- 创建任务:
POST /api/v3/contents/generations/tasks - 查询任务:
GET /api/v3/contents/generations/tasks/{task_id}
Wan 3.0
- 模型:
wan3.0-video、wan3.0-video-prime input.prompt与input.media至少填写一项;提示词最多 5000 个字符- 分辨率:
480P、720P、1080P,默认1080P - 比例:
adaptive、16:9、9:16、1:1、4:3、3:4,默认adaptive - 时长:2 至 30 秒,默认 5 秒;传
-1时由模型智能选择时长 - 提示词改写:
parameters.prompt_extend默认为true;设为false可减少约 20 至 60 秒处理时间,但可能降低生成效果 - 素材类型:
reference_image、reference_video、reference_audio、first_frame、last_frame、file、link
Wan 3.0 支持文生视频、首帧 / 首尾帧视频生成,以及基于图片、视频、音频、文件或网页的参考视频生成。first_frame / last_frame 不能与参考素材、文件或网页混用,且 last_frame 必须搭配 first_frame。最多输入 10 张参考图、5 段参考视频和 5 段参考音频;参考视频与参考音频各自总时长不超过 15 秒。使用 file 或 link 时必须设置 parameters.enable_thinking: true,二者最多传一个且不能同时使用。
curl -X POST "$BASE_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan3.0-video",
"input": {
"prompt": "参考图中的人物走进参考视频的场景,并使用参考音频中的声音说话",
"media": [
{"type": "reference_image", "url": "https://example.com/character.png"},
{"type": "reference_video", "url": "https://example.com/scene.mp4"},
{"type": "reference_audio", "url": "https://example.com/voice.mp3"}
]
},
"parameters": {
"resolution": "1080P",
"ratio": "adaptive",
"duration": -1,
"audio": true,
"prompt_extend": true,
"watermark": false
}
}'包含参考视频时,输入与输出视频总时长不能超过 30 秒。
Wan 2.7
- 模型:
wan2.7-t2v、wan2.7-i2v、wan2.7-r2v - 分辨率:
720P、1080P,默认1080P - 时长:2 至 15 秒,默认 5 秒;
r2v使用参考视频时输出最长 10 秒 t2v/r2v支持16:9、9:16、1:1、4:3、3:4,默认16:9;i2v跟随输入素材比例
文生视频
curl -X POST "$BASE_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.7-t2v",
"input": {
"prompt": "清晨的山谷云海翻涌,镜头缓慢向前推进,电影感自然光"
},
"parameters": {
"resolution": "1080P",
"duration": 5,
"ratio": "16:9",
"watermark": false
}
}'图生视频
wan2.7-i2v 在 input.media 中使用 first_frame、last_frame、driving_audio 或 first_clip:
{
"model": "wan2.7-i2v",
"input": {
"prompt": "人物自然转身看向镜头,背景保持稳定",
"media": [
{"type": "first_frame", "url": "https://example.com/first-frame.png"},
{"type": "last_frame", "url": "https://example.com/last-frame.png"}
]
},
"parameters": {"resolution": "1080P", "duration": 5, "watermark": false}
}参考生视频
wan2.7-r2v 的 input.media 必须包含 reference_image 或 reference_video:
{
"model": "wan2.7-r2v",
"input": {
"prompt": "保持参考图人物外观一致,镜头平稳跟随",
"media": [
{"type": "reference_image", "url": "https://example.com/reference.png"}
]
},
"parameters": {"resolution": "1080P", "duration": 5, "ratio": "16:9"}
}查询任务
curl "$BASE_URL/api/v3/contents/generations/tasks/<task_id>" \
-H "Authorization: Bearer $API_KEY"| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 任务 ID。 |
model |
string | 创建任务时使用的模型。 |
status |
string | 任务进度状态:queued、running、succeeded 或 failed。 |
created_at |
integer | 任务创建时间,Unix 时间戳。 |
updated_at |
integer | 任务状态更新时间,Unix 时间戳。 |
content |
object / null | 任务成功时返回结果对象,视频地址位于 content.video_url。 |
usage |
object / null | 任务用量信息,可能为 null。 |
error |
object / null | 失败信息,任务失败时读取 error.code 和 error.message。 |
{
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"model": "wan3.0-video",
"status": "succeeded",
"created_at": 1779381684,
"updated_at": 1779381864,
"content": {
"video_url": "https://example.com/generated-video.mp4"
},
"usage": null,
"error": null
}queued 或 running 时继续按合理间隔查询;succeeded 时从 content.video_url 读取视频地址;failed 时读取 error.code 和 error.message。任务 ID 与完成后的视频地址均在 24 小时内有效,请及时下载或转存视频。
参考文件、首段续写与参数
Wan 3.0 支持以 file 引用 PDF、文本或常见办公文档。参考服务记录单个文档最多 100 MB,分页文档还须在 50 页以内。使用 link 时,网页应无需登录且可从公网访问。文件和网页都需要开启 parameters.enable_thinking。参考服务也列出 parameters.audio、parameters.watermark 和 parameters.seed,分别控制输出音轨、水印和种子。
Wan 2.7 的 wan2.7-i2v 支持用 first_clip 提供首段视频来续写,parameters.duration 在此模式下表示输入片段加续写的总时长。用 driving_audio 驱动视频时需同时提供首帧,也可再提供尾帧。参考服务限定在同一 input.media 内同一素材类型最多出现一次。对于 wan2.7-r2v,参考媒体至少包含 reference_image 或 reference_video。
媒体格式与可选控制参数
| Wan 3.0 素材 | 单项限制 |
|---|---|
| 参考图、首帧、尾帧 | JPG、JPEG、PNG、BMP、WEBP。去除透明通道,每张不超过 20 MB,每边 240–8000 像素,长边与短边之比不超过 8:1 |
| 参考视频 | MP4、MOV。每段 1–15 秒,文件小于 100 MB,每边 240–4096 像素,长边与短边之比不超过 8:1 |
| 参考音频 | WAV、MP3。每段 1–15 秒,文件小于 15 MB |
Wan 3.0 的 parameters.audio 默认开启,关闭音轨保持原计费价格。parameters.enable_thinking 默认关闭,parameters.watermark 默认关闭。Wan 3.0 和 Wan 2.7 的 parameters.seed 接受 0 至 2147483647 的整数。Wan 2.7 还可用 input.negative_prompt 描述应避免的画面,parameters.prompt_extend 默认开启,parameters.watermark 默认关闭。
Wan 3.0 首尾帧与文件引用
将示例请求体发送至 POST /api/v3/contents/generations/tasks。首尾帧模式各可指定一张图。
{
"model": "wan3.0-video",
"input": {
"prompt": "玻璃温室从拂晓过渡到日出,保持相机位置。",
"media": [
{"type": "first_frame", "url": "https://example.com/greenhouse-dawn.jpg"},
{"type": "last_frame", "url": "https://example.com/greenhouse-sunrise.jpg"}
]
},
"parameters": {"resolution": "720P", "ratio": "adaptive", "duration": 8}
}用文档生成短片时使用 file,并启用 enable_thinking。
{
"model": "wan3.0-video",
"input": {
"prompt": "根据手册制作一段展示装配流程的短片。",
"media": [{"type": "file", "url": "https://example.com/assembly-guide.pdf"}]
},
"parameters": {"resolution": "720P", "duration": -1, "enable_thinking": true}
}Wan 2.7 续写视频
以下使用 first_clip 传入片段,并通过 last_frame 指定结尾画面。duration 是整段结果的目标秒数。
{
"model": "wan2.7-i2v",
"input": {
"prompt": "接续自行车入镜的动作,然后停在石墙旁。",
"media": [
{"type": "first_clip", "url": "https://example.com/bicycle-entry.mp4"},
{"type": "last_frame", "url": "https://example.com/bicycle-stop.png"}
]
},
"parameters": {"resolution": "720P", "duration": 9}
}创建成功后保留响应中的 id 或 task_id,用于后续查询。 Wan 视频参考文档
MiniMax-H3 视频生成
#本章目录
- 创建任务:
POST /v2/video_generation - 查询任务:
GET /v2/query/video_generation/{task_id} - 模型:
MiniMax-H3
请求体使用多模态 content 数组,必须包含一个非空 text 项;可加入首帧、尾帧、参考图片、参考视频和参考音频。resolution 支持 768P、2K,duration 在纯文本输入时使用 5 至 15 的整数秒,包含媒体输入时使用 5、10 或 15 秒。文生视频的 ratio 需传入具体比例;包含媒体输入时可使用 adaptive。
curl -X POST "$BASE_URL/v2/video_generation" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"content": [
{"type": "text", "text": "一位宇航员站在月面,远处的地球从地平线升起。"}
],
"resolution": "2K",
"duration": 5,
"ratio": "16:9"
}'创建成功后保存响应中的 task_id:
{"task_id":"task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}查询任务
curl "$BASE_URL/v2/query/video_generation/<task_id>" \
-H "Authorization: Bearer $API_KEY"查询响应中的 task.status 包括 submitting、submission_unknown、queued、running、succeeded、failed 和 cancelled。任务成功时从 task.content.url 读取视频地址;失败时读取 task.error.code 和 task.error.message。
{
"task": {
"id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"model": "MiniMax-H3",
"status": "succeeded",
"content": {"url": "https://example.com/generated-video.mp4"},
"resolution": "2K",
"duration": 5,
"ratio": "16:9",
"usage": {"total_seconds": 5, "input_seconds": 0, "output_seconds": 5, "input_image_count": 0},
"task_type": "generation",
"modality": "video"
}
}建议每隔 5 至 10 秒查询一次。任务处于 submitting、submission_unknown、queued 或 running 时继续等待,不重复创建;succeeded 时下载视频;cancelled 时停止轮询。视频下载地址有时效,成功后请及时下载或转存。对 429 和临时 5xx 响应使用带随机抖动的指数退避。
多模态参考输入
每个媒体项通过 role 指定用途。参考服务记录提示词最多 7000 字符,首帧和尾帧各最多一张,参考图最多九张。参考视频和参考音频各最多三段,每段 2 至 15 秒,各类媒体合计时长分别不超过 15 秒。可使用 aigc_watermark 控制生成标识水印。
| 输入 | type |
role |
地址字段 |
|---|---|---|---|
| 图片 | image_url |
first_frame、last_frame 或 reference_image |
image_url.url |
| 视频 | video_url |
reference_video |
video_url.url |
| 音频 | audio_url |
reference_audio |
audio_url.url |
查询失败任务时优先展示 task.error.message。用量信息可能省略,其中 task.usage.input_audio_seconds 对应输入参考音频的时长。
媒体尺寸与组合
| 类型 | 格式与容量 |
|---|---|
| 图片 | JPG、JPEG、PNG、WEBP、HEIC、HEIF。每张至多 30 MB,宽高各为 256–5760 像素,宽高比为 0.4–2.5 |
| 视频 | MP4、MOV,每段至多 50 MB |
| 音频 | WAV、MP3,每段至多 15 MB |
请求体至多 64 MB,媒体项合计最多 12 项,地址使用公网 URL。单张图片省略 role 时视为 first_frame。首尾帧和参考媒体应分别提交。参考音频须搭配参考图或参考视频。可选画幅为 21:9、16:9、4:3、1:1、3:4、9:16 和 adaptive,其中纯文本请求使用具体画幅。aigc_watermark 默认为 false。
首尾帧和多模态请求体
将以下请求体分别提交到 POST /v2/video_generation。
{
"model": "MiniMax-H3",
"content": [
{"type": "text", "text": "用单个长镜头从海边阶梯缓慢移到灯塔。"},
{"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/stairs.jpg"}},
{"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/lighthouse.jpg"}}
],
"resolution": "768P",
"duration": 10,
"ratio": "adaptive"
}{
"model": "MiniMax-H3",
"content": [
{"type": "text", "text": "让参考图里的橙色皮划艇经过参考视频中的浮标,沿用海浪声。"},
{"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/kayak.jpg"}},
{"type": "video_url", "role": "reference_video", "video_url": {"url": "https://example.com/buoys.mp4"}},
{"type": "audio_url", "role": "reference_audio", "audio_url": {"url": "https://example.com/waves.wav"}}
],
"resolution": "768P",
"duration": 10,
"ratio": "adaptive"
}task.created_at 和 task.updated_at 使用秒级 Unix 时间戳。轮询期间,时间、产物规格和用量字段可能尚未填充,应根据 task.status 判断何时读取产物或错误详情。 MiniMax 视频参考文档
Happyhorse 视频
#- 创建任务:
POST /v1/videos - 查询任务:
GET /v1/videos/{task_id} - 模型:
happyhorse-1.0-t2v、happyhorse-1.0-i2v、happyhorse-1.0-r2v、happyhorse-1.0-video-edit
视频生成是异步任务。素材图片或视频必须使用公网可访问的文件直链。
文生视频
curl -X POST "$BASE_URL/v1/videos" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0-t2v",
"input": {
"prompt": "一匹白色小马在草原上奔跑,电影感镜头"
},
"parameters": {
"resolution": "720P",
"duration": 5,
"ratio": "16:9",
"watermark": false
}
}'图生视频使用 happyhorse-1.0-i2v,并在 input.media 中传入 type: "input_image" 和图片 URL;参考图生视频使用 happyhorse-1.0-r2v 与 type: "reference_image";视频编辑使用 happyhorse-1.0-video-edit 与 type: "video"。
查询任务
curl "$BASE_URL/v1/videos/<task_id>" \
-H "Authorization: Bearer $API_KEY"任务状态包括 queued、in_progress、completed、failed、cancelled。完成后从 metadata.url 读取视频地址。
视频编辑与任务响应
编辑任务使用 happyhorse-1.0-video-edit。用于计费的影片时长填写在请求顶层 duration。媒体项的 type 使用 video,如需沿用输入音轨,可设置 parameters.audio_setting: "origin"。
curl "$BASE_URL/v1/videos" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "happyhorse-1.0-video-edit",
"duration": 3,
"input": {
"prompt": "将夕阳下的画面调成冷色,保留原来的镜头运动",
"media": [{"type": "video", "url": "https://example.com/video/source.mp4"}]
},
"parameters": {"resolution": "720P", "audio_setting": "origin"}
}'从创建响应保存 id 或 task_id,供查询接口使用。查询响应还可包含 progress 与 error,分别用于展示进度及定位失败原因。
输入图和多参考图示例
下面两个请求体使用 POST /v1/videos。图片使用服务端可直接下载的公网地址。参考图可通过提示词里的 [Image 1]、[Image 2] 对应至 input.media 中的顺序。
{
"model": "happyhorse-1.0-i2v",
"input": {
"prompt": "让水面轻轻泛起涟漪,保持岸边景物静止。",
"media": [{"type": "input_image", "url": "https://example.com/pond.jpg"}]
},
"parameters": {"resolution": "720P", "duration": 5, "watermark": false}
}{
"model": "happyhorse-1.0-r2v",
"input": {
"prompt": "把 [Image 1] 的雕塑放在 [Image 2] 的展厅中,镜头缓慢环绕。",
"media": [
{"type": "reference_image", "url": "https://example.com/sculpture.jpg"},
{"type": "reference_image", "url": "https://example.com/gallery.jpg"}
]
},
"parameters": {"resolution": "720P", "duration": 3, "ratio": "16:9", "watermark": false}
}查询完成响应
创建响应可包含 created_at,用于记录排队时间。查询返回 completed 后,可从 metadata.url 下载视频。
{
"id": "<TASK_ID>",
"task_id": "<TASK_ID>",
"model": "happyhorse-1.0-r2v",
"status": "completed",
"progress": 100,
"metadata": {"url": "https://example.com/gallery-result.mp4"},
"error": null
}语音合成 TTS
#- 接口:
POST /v1/audio/speech - 返回内容为音频二进制,应按文件流保存
curl "$BASE_URL/v1/audio/speech" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-tts-flash",
"input": "你好,这是一个测试。",
"voice": "Cherry"
}' \
--output speech.wavqwen3-tts-flash 常用音色为 Cherry;MiniMax 模型常用音色为 male-qn-qingse。可通过 response_format 指定音频格式,通过 speed 调整语速。
MiniMax 模型与保存音频
参考服务通过同一 POST /v1/audio/speech 接口提供 MiniMax/speech-2.8-turbo 和 MiniMax/speech-2.8-hd,这两个型号的示例音色为 male-qn-qingse。请求指定 response_format 后,按相应扩展名保存响应。
curl --fail "$BASE_URL/v1/audio/speech" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax/speech-2.8-turbo",
"input": "感谢收听今天的城市漫步播报。",
"voice": "male-qn-qingse",
"response_format": "mp3"
}' \
--output announcement.mp3参考:语音合成模型、音色与格式
音频请求字段
| 字段 | 类型 | 说明 |
|---|---|---|
model |
string,必填 | 使用当前密钥可访问的语音合成模型。 |
input |
string,必填 | 待朗读的文本。 |
voice |
string,必填 | 使用所选模型支持的音色 ID。 |
response_format |
string | 指定模型支持的音频格式,例如 mp3。 |
speed |
number | 调整语速,取值范围以模型支持情况为准。 |
在 Python 中保存二进制音频
安装 openai 并设置 API_KEY。指定 response_format="wav" 后,按相同格式命名文件。
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key=os.environ["API_KEY"],
base_url="https://token.axicomin.cn/v1",
)
with client.audio.speech.with_streaming_response.create(
model="qwen3-tts-flash",
voice="Cherry",
input="下一站是图书馆,请从右侧车门下车。",
response_format="wav",
) as audio:
audio.stream_to_file(Path("station.wav"))实时语音识别
#- 协议:WebSocket ASR
- 模型:
qwen-audio-3.0-asr-flash-streaming - 接口:
GET /api-ws/v1/inference,通过 WebSocket 升级
在握手请求头传入 Authorization: Bearer <YOUR_API_KEY>。以下示例使用 Python 3.11+ 和 websockets 14+,按单声道、16 bit、16 kHz WAV 文件中的 PCM 数据进行并行收发:
export ASR_API_KEY="$API_KEY"
export ASR_WS_URL="${BASE_URL/https:/wss:}/api-ws/v1/inference"import asyncio
import json
import os
import uuid
import wave
import websockets
async def send_audio(ws, path, task_id):
with wave.open(path, "rb") as audio:
if (audio.getnchannels(), audio.getsampwidth(), audio.getframerate()) != (1, 2, 16000):
raise ValueError("需要单声道、16 bit、16 kHz WAV 文件")
while chunk := audio.readframes(1600):
await ws.send(chunk)
await asyncio.sleep(len(chunk) / 32000)
await ws.send(json.dumps({
"header": {"action": "finish-task", "task_id": task_id, "streaming": "duplex"},
"payload": {"input": {}},
}))
async def receive_results(ws):
sentences = {}
duration = None
while True:
event = json.loads(await asyncio.wait_for(ws.recv(), timeout=60))
kind = event.get("header", {}).get("event")
if kind == "task-failed":
raise RuntimeError(event["header"])
payload = event.get("payload") or {}
sentence = (payload.get("output") or {}).get("sentence") or {}
if kind == "result-generated" and sentence.get("sentence_end") and not sentence.get("heartbeat"):
sentences[sentence["sentence_id"]] = sentence.get("text", "")
usage = payload.get("usage")
if usage is not None:
reported = usage.get("duration")
if isinstance(reported, (int, float)):
duration = reported if duration is None else max(duration, reported)
if kind == "task-finished":
print("".join(sentences[key] for key in sorted(sentences)))
print(f"累计音频秒数:{duration if duration is not None else '未返回'}")
return
async def recognize(path):
task_id = str(uuid.uuid4())
headers = {"Authorization": f"Bearer {os.environ['ASR_API_KEY']}"}
async with websockets.connect(os.environ["ASR_WS_URL"], additional_headers=headers) as ws:
await ws.send(json.dumps({
"header": {"action": "run-task", "task_id": task_id, "streaming": "duplex"},
"payload": {
"task_group": "audio", "task": "asr", "function": "recognition",
"model": "qwen-audio-3.0-asr-flash-streaming",
"parameters": {"format": "pcm", "sample_rate": 16000},
"input": {"context": []},
},
}))
started = json.loads(await asyncio.wait_for(ws.recv(), timeout=30))
if started.get("header", {}).get("event") != "task-started":
raise RuntimeError(started)
async with asyncio.TaskGroup() as tasks:
tasks.create_task(send_audio(ws, path, task_id))
tasks.create_task(receive_results(ws))
asyncio.run(recognize("sample.wav"))run-task 的 header.task_id 必须为新的 UUID;header.streaming 固定为 duplex,payload.parameters.format 支持 pcm、wav、mp3、opus、speex、aac、amr,sample_rate 必须与音频一致。收到 task-started 后再发送二进制音频,每条消息不超过 1 MiB;发送 finish-task 后继续接收 result-generated,直到 task-finished。
payload.output.sentence 包含识别文字和 sentence_end;payload.usage.duration 是当前任务累计秒数,可能为 null,不要把多条事件的时长相加。task-failed 的 header.error_code 和 header.error_message 表示失败,应关闭连接并以新的任务 ID 重试。网页浏览器不能自行设置 WebSocket 的 Authorization 请求头。
音频封装与识别错误
WAV 应封装 PCM,Opus 和 Speex 使用 Ogg 容器,AMR 使用 AMR-NB。将其他格式转码为示例使用的 16 kHz、16 bit 单声道 PCM WAV,可以先在本地运行:
ffmpeg -i input.m4a -vn -ac 1 -ar 16000 -c:a pcm_s16le asr-input.wav记录 payload.output.sentence.sentence_id,收到同一句的新结果时更新已有显示。用 sentence_end 判断该句是否已经结束。识别文字和用量分别处理,累计时长保留同一任务已收到的最大值。
遇到 InvalidParameter,检查音频编码、起始事件与任务 ID。遇到 Throttling,降低发起频率再重试。遇到 AccessDenied、QuotaExhausted 或 ModelNotSupported,检查模型权限、额度与型号配置。
WebSocket 控制帧与事件
WebSocket 地址为 wss://token.axicomin.cn/api-ws/v1/inference。用文本帧发送 JSON 控制消息,收到 task-started 后以二进制帧发送音频。
| 启动帧字段 | 值或用途 |
|---|---|
header.action、header.streaming |
固定值 run-task、duplex。结束时将动作改为 finish-task。 |
header.task_id |
每次任务生成一个 UUID,同一次任务的所有控制帧使用同一 ID。 |
payload.task_group、payload.task、payload.function |
固定值 audio、asr、recognition。 |
payload.parameters.format、sample_rate |
必须与音频编码和实际采样率匹配。 |
payload.parameters.semantic_punctuation_enabled |
可选布尔值,用于启用语义标点。 |
payload.input.context |
可选识别上下文,无上下文时可传空数组。 |
| 服务端事件 | 客户端处理 |
|---|---|
task-started |
可以发送音频帧。 |
result-generated |
用 payload.output.sentence.text 更新识别文字,用 sentence_id 对应句子,sentence_end 标记定稿。 |
task-finished |
收齐最终结果。若该事件的用量为空,保留此前接收的累计时长。 |
task-failed |
停止发送音频,并记录 header.error_code、header.error_message 和任务 ID。 |
同一连接可顺序开启新任务,每个任务使用新的 UUID。发送 finish-task 后等到 task-finished 再关闭连接。连接中断后,最终识别结果无法通过任务查询恢复,需要重新发送音频,已产生的用量可能仍会计费。
多模态向量
#- 协议:OpenAI Embeddings
- 模型:
qwen3-vl-embedding - 接口:
POST /v1/embeddings
input.contents 支持文本、图片和视频。图片与视频传入可公开访问的 HTTP(S) URL;一次请求最多 20 个内容,其中图片最多 10 个、视频最多 1 个。
curl "$BASE_URL/v1/embeddings" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-vl-embedding",
"input": {
"contents": [
{"text": "一只猫坐在窗边"},
{"image": "https://example.com/images/cat.png"},
{"video": "https://example.com/videos/cat.mp4"}
]
},
"parameters": {
"dimension": 1024,
"fps": 0.5,
"output_type": "dense"
}
}'启用融合向量时,在 parameters 中设置 "enable_fusion": true,请求会返回一个融合结果。parameters.dimension 支持 256、512、768、1024、1536、2048 和 2560。
响应使用 OpenAI Embeddings 结构:object 为 list,向量位于 data[].embedding,data[].index 对应输入内容索引;usage.prompt_tokens_details.text_tokens 和 usage.prompt_tokens_details.image_tokens 分别表示文本和视觉内容的 token 用量。
{
"object": "list",
"data": [
{"object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789]},
{"object": "embedding", "index": 1, "embedding": [0.0234, -0.0345, 0.0678]}
],
"model": "qwen3-vl-embedding",
"usage": {
"prompt_tokens": 18,
"total_tokens": 18,
"prompt_tokens_details": {"text_tokens": 12, "image_tokens": 6}
}
}输出向量设置
input.contents[] 的元素可以是文本字符串,也可以是只含 text、image、video 之一的对象。参考服务默认向量维数为 2560。存储向量的索引维数应与请求使用的 parameters.dimension 一致。
| 可选参数 | 说明 |
|---|---|
parameters.instruct |
补充向量生成的任务目标。 |
parameters.fps |
视频抽帧比例,参考文档给出的范围为 0 至 1,默认 1。 |
parameters.output_type |
参考文档当前列出的值为 dense。 |
参考:多模态向量参数与响应
独立向量与融合向量
| 模式 | 设置 | 读取结果 |
|---|---|---|
| 独立向量 | parameters.enable_fusion: false,默认值 |
根据各 data[].index 关联原输入,对每条内容单独建索引。 |
| 融合向量 | parameters.enable_fusion: true |
读取返回的单个 data[0].embedding,按一条记录保存组合内容。 |
使用 Python 生成融合向量
安装 requests,设置 API_KEY,并将 IMAGE_URL 设为调用服务能公开访问的图片地址。直接发送 JSON,可以传入该模型专用的 input.contents 和 parameters 对象。
import os
import requests
response = requests.post(
"https://token.axicomin.cn/v1/embeddings",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
json={
"model": "qwen3-vl-embedding",
"input": {
"contents": [
{"text": "冬季河岸风景"},
{"image": os.environ["IMAGE_URL"]},
]
},
"parameters": {
"dimension": 1024,
"enable_fusion": True,
"instruct": "生成用于图文检索的向量。",
"output_type": "dense",
},
},
timeout=60,
)
response.raise_for_status()
result = response.json()
vector = result["data"][0]["embedding"]
print(f"融合向量维度:{len(vector)}")
print(f"输入 token:{result['usage']['prompt_tokens']}")3D 模型生成
#本章目录
- 协议:3D Tasks
- 模型:
tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1、tripo-p2、tripo-splat - 图片输入使用可公开访问的 HTTP(S) 图片 URL。生成以异步任务运行;创建成功后保存
data.task_id并使用查询接口读取状态和结果。
创建文本生成 3D 任务
- 接口:
POST /v3/generation/text-to-model model使用tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1或tripo-p2。prompt必填,长度为 1 至 1024 个字符;negative_prompt可选,最多 255 个字符。可选参数还包括image_seed、model_seed和网格生成参数。
curl -X POST "$BASE_URL/v3/generation/text-to-model" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tripo-v3.1","prompt":"一把带有雕刻细节的中世纪木椅,正面视角","texture_quality":"standard","geometry_quality":"standard"}'创建图片生成 3D 任务
- 接口:
POST /v3/generation/image-to-model model使用tripo-v3.1、tripo-v3.0、tripo-v2.5、tripo-p1或tripo-p2;input必填,传入一张图片的公网 HTTP(S) URL。- 可选传入
model_seed和网格生成参数。
curl -X POST "$BASE_URL/v3/generation/image-to-model" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tripo-v3.1","input":"https://example.com/images/chair-front.jpg","model_seed":42,"face_limit":10000}'创建多视图 3D 任务
- 接口:
POST /v3/generation/multiview-to-model inputs必填,包含 2 至 4 个视角,必须包含front和至少一个其他视角。视角键为front、left、back或right。- 每个视角可传 URL 字符串或
{"url":"..."}对象,也可传入四个位置的 URL 数组;正面图片放在第一项,空视角使用空字符串。
curl -X POST "$BASE_URL/v3/generation/multiview-to-model" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tripo-v3.1","inputs":[{"front":"https://example.com/images/object-front.jpg"},{"back":"https://example.com/images/object-back.jpg"}],"texture_quality":"standard"}'创建 Gaussian Splat 任务
- 接口:
POST /v3/generation/image-to-splat model固定为tripo-splat;input必填,传入一张图片的公网 HTTP(S) URL;可选传入model_seed。
curl -X POST "$BASE_URL/v3/generation/image-to-splat" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"tripo-splat","input":"https://example.com/images/garden.jpg","model_seed":42}'网格生成参数
以下可选参数用于文本、图片和多视图任务,可用值和组合限制受所选模型能力约束。
| 参数 | 类型 | 说明 |
|---|---|---|
texture、pbr |
boolean | 是否生成纹理和 PBR 材质。 |
texture_quality |
string | fast、standard、detailed 或 extreme。fast 需同时设置 texture_version 为 v3.5-20260815。 |
texture_version |
string | v3.5-20260815、v3.0-20250812 或 v2.5-20250123。 |
geometry_quality |
string | standard 或 detailed。 |
image_seed、texture_seed、model_seed |
integer | 图片、纹理或模型生成种子。 |
face_limit |
integer | 必须为正整数;可用范围受模型和几何参数影响。 |
texture_alignment |
string | original_image 或 geometry。 |
orientation |
string | default 或 align_image。 |
auto_size、delight、quad、smart_low_poly、generate_parts、export_uv、enable_image_autofix |
boolean | 控制尺寸调整、纹理优化、网格拓扑、分部件、UV 导出或图片修复。generate_parts 要求 texture 和 pbr 均为 false。 |
compress |
string | geometry。 |
export_orientation |
string | +x、-x、-y 或 +y。 |
查询 3D 生成任务
- 接口:
GET /v3/tasks/{task_id}。 - 状态包括
queued、running、success、failed、banned、expired和cancelled。 - 成功时从
data.output.model_url读取模型地址;失败时查看data.error_message。 - 可选传入最长 128 个字符的
Idempotency-Key。相同 API Key 使用相同键和相同请求重试时会复用任务;相同键用于不同请求时返回 HTTP409。
curl "$BASE_URL/v3/tasks/task_01JEXAMPLE3D" \
-H "Authorization: Bearer $API_KEY"{
"code": 0,
"data": {
"task_id": "task_01JEXAMPLE3D",
"type": "text_to_model",
"status": "success",
"progress": 100,
"created_at": "2026-10-21T08:30:00Z",
"completed_at": "2026-10-21T08:31:12Z",
"output": {
"model_url": "https://models.example.com/generated/chair.glb",
"rendered_image_url": "https://models.example.com/generated/chair-preview.png"
}
}
}预览资源与查询进度
轮询时,data.progress 可用于进度展示。完成后,如响应同时给出 data.output.rendered_image_url 或 data.output.generated_image_url,可把它们作为模型预览与生成图资源。失败时可同时保留 data.error_code 和 data.error_message,便于定位具体问题。
参考:3D 模型任务与输出字段
多视图输入格式
可用对象按视角命名。此例混合字符串 URL 与 `url 对象。
{
"model": "tripo-v3.1",
"inputs": [
{"front": "https://example.com/lantern/front.png"},
{"left": {"url": "https://example.com/lantern/left.png"}}
],
"model_seed": 17
}位置数组须保留四个槽位,缺失视角填空字符串。下面提供正面、左侧和右侧图片。
{
"model": "tripo-v3.1",
"inputs": [
"https://example.com/lantern/front.png",
"https://example.com/lantern/left.png",
"",
"https://example.com/lantern/right.png"
]
}任务结果字段
| 字段 | 说明 |
|---|---|
code、data.task_id |
成功时 code 为 0。创建后保存任务 ID。 |
| `data.type | text_to_model、image_to_model、multiview_to_model 或 image_to_splat。 |
data.status、data.progress |
当前状态和 0 至 100 的任务进度。 |
data.created_at、data.completed_at |
RFC 3339 时间。完成时间随已结束任务返回。 |
| `data.output.model_url | 生成结果地址,成功后及时下载。 |
| `data.output.rendered_image_url | 可选的渲染预览图地址。 |
| `data.output.generated_image_url | 可选的生成图片地址。 |
data.error_code、data.error_message |
失败时的错误码和解释,按可用字段处理。 |