API 参考 最后更新

大模型 API 接入文档

本文档提供文本、图片、视频、语音、多模态向量和 3D 模型的标准接入方式。实际可用模型以当前 API Key 调用 GET /v1/models 的返回结果为准。

Base URL https://token.axicomin.cn/

快速开始

#

调用模型使用平台 API Key。首次接入时,先配置好凭证,再从模型列表中选出当前账户可用的模型。

创建模型 API Key

  1. 登录平台控制台,进入 API 密钥。
  2. 新建密钥并起一个便于识别的名称,例如 `development。按当前控制台提供的选项设置分组或使用限制。
  3. 将完整密钥保存到密码管理器或服务端的环境变量。密钥疑似泄露时,在控制台停用或删除旧密钥并替换应用配置。

验证连接

Bash
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 管理密钥时,应使用 个人令牌。

参考快速开始

全局配置

#
Bash
BASE_URL="https://token.axicomin.cn"
API_KEY="<YOUR_API_KEY>"

鉴权

除 Seedance 素材资产库可选的 Ark AK/SK 兼容认证外,所有接口使用平台 API Key 鉴权:

HTTP
Authorization: Bearer <YOUR_API_KEY>

请求追踪

客户端应在每次请求后记录响应头中的 X-Oneapi-Request-Id。该值是问题排查所需的日志定位 ID;反馈接口问题时请一并提供。

查询可用模型

#
Bash
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 兼容协议和用户级接口使用不同的路径及授权方式。可从 全局配置、用户与密钥管理 和 错误处理 查看对应细节。

参考接入规范

错误处理与重试

#
  1. 对 HTTP 429 和临时性 5xx 响应采用带抖动的指数退避,不要无间隔重试。
  2. 视频任务创建成功后按建议间隔轮询,不要高频查询任务状态。
  3. 写请求遇到网络超时且无法确认服务端是否接收时,优先复用原 Idempotency-Key 重试。
  4. 保留响应头 X-Oneapi-Request-Id,用于接口问题定位。
  5. TTS 返回二进制音频;图片模型可能返回 Base64 或 URL;视频模型返回异步任务 ID。客户端应按接口响应类型分别处理。

个人令牌

#

查询账户或管理 API Key 时,在 Authorization 请求头中使用个人令牌。模型接口(例如 GET /v1/models)使用单独创建的 API Key。

登录控制台,在「安全与访问」的「会话与访问」下找到「访问令牌」,选择「生成」。重新生成后,旧令牌立即失效。将新令牌保存在环境变量或凭据库,避免把它写入日志和共享文件。 安全与访问

Bash
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 对象读取余额和累计用量。

Bash
curl "$BASE_URL/api/user/self" -H "$AUTH_HEADER"
字段 内容
data.quota 当前可用额度
data.used_quota 累计消耗的额度
data.request_count 累计请求笔数
JSON
{
  "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 名称
Bash
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
Bash
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 可使用返回的分组名。

Bash
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 禁用
Bash
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}'
Bash
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[] 同一结构的对象。

Bash
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。

Bash
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。

Bash
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 表示无到期时间。

Bash
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。

Bash
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 随即失效。

Bash
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 读取密钥。用环境变量或应用的凭据存储提供密钥,避免把真实值写入项目配置、日志或截图。在启动工具的同一个终端中设置变量,例如:

Bash
export AXICOMIN_API_KEY="<YOUR_API_KEY>"
PowerShell
$env:AXICOMIN_API_KEY = "<YOUR_API_KEY>"

模型还需要支持所选工具的协议及工具调用。配置完成后可以先发送一个简短的对话,再验证一项只读操作,例如概述当前目录。

现象 检查项
401 密钥是否有效,启动进程能否读取密钥,客户端是否按该指南发送 Bearer 凭据
404、找不到模型 Base URL 的 /v1 是否正确,模型 ID 是否逐字匹配 模型列表 的返回值
能对话但无法调用工具 模型是否支持工具调用,当前工作目录和客户端权限是否允许该操作

接入 Agent 工具参考

Claude Code

#
本章目录

Claude Code 使用 Anthropic Messages,调用 POST /v1/messages。

安装与版本检查

在 macOS、Linux 或 WSL 中运行:

Bash
curl -fsSL https://claude.ai/install.sh | bash
claude --version

在 Windows PowerShell 中运行:

PowerShell
irm https://claude.ai/install.ps1 | iex
claude --version

在 Windows 命令提示符中运行:

cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
claude --version

Claude Code 安装指南

在终端启动

在已设置 AXICOMIN_API_KEY 的终端中执行以下配置。Base URL 填站点根地址,Claude Code 会拼接 /v1/messages。ANTHROPIC_AUTH_TOKEN 对应 Authorization: Bearer。

Bash
export ANTHROPIC_BASE_URL="https://token.axicomin.cn"
export ANTHROPIC_AUTH_TOKEN="$AXICOMIN_API_KEY"
export ANTHROPIC_MODEL="<MODEL_ID>"
claude

Windows PowerShell 中使用以下写法:

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。

JSON
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://token.axicomin.cn",
    "ANTHROPIC_MODEL": "<MODEL_ID>"
  }
}

启动后用 /status 检查配置,发送一句问候验证连接。若已有登录状态导致鉴权冲突,可在 Claude Code 中执行 /logout,再从配置好环境的终端启动。

平台接入参考 · Claude Code 网关配置

Codex

#

Codex CLI 可以把 Responses API 路由到自定义供应商。安装客户端并确认版本后,从能读取 AXICOMIN_API_KEY 的终端启动。

Bash
npm install -g @openai/codex
codex --version

配置模型供应商

在用户级 ~/.codex/config.toml 中合并以下字段。将 model 填为支持 Responses API 的模型 ID。自定义供应商名称 axicomin 要与 model_provider 的值一致。

TOML
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。保存后在项目目录启动:

Bash
codex

请它概述当前目录来验证连接。收到 401 时检查环境变量是否随进程启动传入。请求地址错误时,检查 wire_api 和 Base URL 的 /v1。

平台接入参考 · Codex 自定义供应商

OpenCode

#
本章目录

OpenCode 的 OpenAI Compatible 适配器调用 POST /v1/chat/completions。在支持 Bash 的环境中可以运行 OpenCode 2 的安装脚本。安装后在启动终端设置 AXICOMIN_API_KEY。

Bash
curl -fsSL https://opencode.ai/v2/install | bash
opencode --version

OpenCode 安装

配置项目

在项目根目录的 opencode.json 合并供应商定义。两个 <MODEL_ID> 均填写同一个完整模型 ID。以下示例使用新版 providers 配置。

JSON
{
  "$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 示例:

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}。

平台旧版接入示例 · OpenCode 供应商配置 · 变量替换

OpenClaw

#
本章目录

OpenClaw 的 openai-completions 适配器调用 POST /v1/chat/completions。

安装与设置密钥

在 macOS、Linux 或 WSL 中运行:

Bash
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw --version

在 Windows PowerShell 中运行:

PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw --version

在用户配置目录 ~/.openclaw/.env 中提供密钥:

.env
AXICOMIN_API_KEY=<YOUR_API_KEY>

注册供应商和模型

把以下字段合并到 ~/.openclaw/openclaw.json。模型列表中的 id 填原始 ID,选择默认模型时使用 axicomin/<MODEL_ID>。请保留已有的 Gateway、渠道和其他供应商配置。

JSON
{
  "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 模型" }
        ]
      }
    }
  }
}

校验并测试

Bash
openclaw config validate
openclaw models list
openclaw models set "axicomin/<MODEL_ID>"

若 Gateway 已作为服务运行,更新 .env 后使用 openclaw gateway restart 重新加载密钥。列表中出现模型后发送一条测试消息。配置校验失败时,先修正报错位置再重新加载。 OpenClaw Gateway 命令

平台接入参考 · OpenClaw 安装 · 自定义供应商字段

Hermes

#

在 Hermes 中添加自定义 OpenAI 兼容端点,通过 POST /v1/chat/completions 访问模型。

安装客户端

在 macOS、Linux 或 WSL 中运行:

Bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

在 Windows PowerShell 中运行:

PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装后重新打开终端,让当前会话读取更新后的命令路径。

配置和验证模型

启动模型配置向导:

Bash
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 并发送一条消息。

Bash
hermes --tui

若无法连接,先运行 hermes doctor。再通过 hermes model 核对协议、Base URL、密钥和模型 ID。

平台接入参考 · Hermes 安装与配置 · Hermes 自定义端点

WorkBuddy

#

WorkBuddy 的自定义模型在应用界面中配置,调用 POST /v1/chat/completions。下载并安装客户端后登录。 WorkBuddy 官网

添加自定义模型

  1. 打开首页输入框右下角的模型选择器,选择 配置自定义模型。
  2. 进入模型设置,点击 添加模型。在供应商列表的 其他 分组选择 自定义。
  3. 填写下表中的三项。高级配置中的 自定义协议 保持关闭。
  4. 点击 测试连接。测试通过后点击 保存。
字段 填写值
接口地址 https://token.axicomin.cn/v1
API Key 平台密钥原值,去除首尾空格
模型名称 模型列表 返回的完整模型 ID

选择并验证

回到首页,打开模型选择器,在 自定义模型 分组选择刚保存的模型。发送一条短消息后,核对回复下方的模型名称。

现象 处理方式
连接失败或密钥无效 从平台重新复制 API Key,检查是否带有首尾空格。
找不到接口 核对接口地址是否以 /v1 结尾,并检查 自定义协议 是否关闭。
模型不存在或无权限 核对完整模型 ID,并检查该模型是否在当前密钥的模型列表中。
保存后找不到模型 回到首页,在输入框的模型选择器中展开 自定义模型。

平台接入参考 · WorkBuddy 模型配置

Chat Completions API

#
本章目录
  • 协议:OpenAI Chat Completions 兼容协议
  • 接口:POST /v1/chat/completions
Bash
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 定义可用工具,以及何时、是否并行调用。
Bash
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
  }'

参考:Chat Completions 请求与响应说明

请求与响应字段

请求字段 类型 用途
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 环境变量。下例依次发送非流式与流式请求,按需保留其中一种调用。

Python
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()

Chat Completions 平台参考 · OpenAI Python 接口

Responses API

#
本章目录
  • 协议:OpenAI Responses
  • 接口:POST /v1/responses
Bash
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。

参考:Responses API 参数与示例

请求与响应字段

请求字段 类型 用途
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 接收事件流

Bash
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,流式响应按事件类型分别处理。

Python
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)

Responses 平台参考 · OpenAI Python 接口

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 调用

Bash
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 读取。

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。

JSON
{
  "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 调用

Bash
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。

Python
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 API 接入说明

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

Bash
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

Bash
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。

Python
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。

Bash
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,单次默认生成一张。参考服务按输出张数计费,实际费率以当前站点为准。

Bash
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 运行同一脚本可以选择按张档。

Python
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")

参考:Gemini 图片接入说明

GPT 图片生成

#
本章目录

GPT Image 兼容接口支持 gpt-image-2。POST /v1/images/generations 用于提示词生图,POST /v1/images/edits 用于以现有图片为输入继续生成。参考服务记录的单次请求产出为一张,可省略 n 或设为 1。默认图片数据位于 data[0].b64_json。

生成新图片

Bash
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,遮罩和原图尺寸应一致,且包含透明通道。

Bash
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。

Bash
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 替换为实际公网图片。

Bash
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。

Python
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。

参考:GPT Image 接入说明

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
Bash
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[] 读取所有结果。

Bash
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"
  }'

参考:Seedream 模型与组图参数

请求字段和保存方式

字段 类型 说明
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 纯文本生图

Bash
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 单张参考图

使用公开图片地址替换此例中的素材。

Bash
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。

Python
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_json
  • wan2.7-image-pro 文生图最高 4K,wan2.7-image 文生图最高 2K;图片编辑使用模型的默认输出规格

文生图:

Bash
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,按上传顺序在提示词中引用图片:

Bash
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 也影响费用。

参考:Wan Image 模型与输入限制

端点参数

字段 端点 说明
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 标准版文生图

Bash
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 单图编辑

Bash
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×2048
  • n 可设为 1 至 6,默认 1;费用按实际生成图片数量核算,具体费率以平台显示为准
  • parameters.prompt_extend 默认为 true;图片 URL 有效期为 24 小时
Bash
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。

Bash
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}
  }'

参考:Qwen Image 参数及编辑示例

完整编辑字段

字段 说明
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
Bash
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 失败。

文生视频
Bash
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"
  }'
素材图生视频
Bash
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。

生成样片
Bash
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"}'
根据样片生成正式视频
Bash
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:

JSON
{
  "id": "cgt-20260730175939-nbf6p"
}

查询视频生成任务

Bash
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 使用指数退避。

删除视频生成任务

Bash
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 任务端点提交。使用前以本平台的模型列表和当前账号权限为准。

参考:Seedance 模型与 Ark 请求参数

首尾帧与视频延长请求体

以下请求体提交到 POST /ark/api/v3/contents/generations/tasks。content 至少包含一个输入项。resolution 可填写 480p、720p 或 1080p,具体挡位由所选模型决定。

指定首尾帧时,画幅跟随首帧。以下用公网图片作为首尾帧,并省略 ratio。

JSON
{
  "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,并在提示词中描述接续的镜头。

JSON
{
  "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
}

查询响应中的输出规格

成功结果同时给出视频直链和实际生成参数。下面保留常用于下载、展示和对账的字段。

JSON
{
  "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 十六进制摘要。
HTTP
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。
Bash
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。
Bash
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。
Bash
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 个字符。
Bash
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。
Bash
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。
Bash
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。
Bash
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。
Bash
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 至少传一个。

Bash
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。
Bash
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 项目名称。
Bash
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"
  }'
JSON
{
  "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 项目名称。
Bash
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"
  }'
JSON
{
  "ResponseMetadata": {
    "RequestId": "req-xxxxxxxx",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "GroupId": "group-xxxxxxxx"
  }
}

错误码

创建或查询视频任务时,如果 HTTP 状态码不是 2xx,响应使用以下结构。param 仅在能够定位到具体参数时返回。

JSON
{
  "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,二者最多传一个且不能同时使用。

Bash
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 跟随输入素材比例

文生视频

Bash
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:

JSON
{
  "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:

JSON
{
  "model": "wan2.7-r2v",
  "input": {
    "prompt": "保持参考图人物外观一致,镜头平稳跟随",
    "media": [
      {"type": "reference_image", "url": "https://example.com/reference.png"}
    ]
  },
  "parameters": {"resolution": "1080P", "duration": 5, "ratio": "16:9"}
}

查询任务

Bash
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。
JSON
{
  "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 视频模型输入与媒体约束

媒体格式与可选控制参数

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。首尾帧模式各可指定一张图。

JSON
{
  "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。

JSON
{
  "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 是整段结果的目标秒数。

JSON
{
  "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。

Bash
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:

JSON
{"task_id":"task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

查询任务

Bash
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。

JSON
{
  "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 对应输入参考音频的时长。

参考:MiniMax-H3 媒体输入与任务响应

媒体尺寸与组合

类型 格式与容量
图片 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。

JSON
{
  "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"
}
JSON
{
  "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

视频生成是异步任务。素材图片或视频必须使用公网可访问的文件直链。

文生视频

Bash
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"。

查询任务

Bash
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"。

Bash
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,分别用于展示进度及定位失败原因。

参考:Happyhorse 接入示例和响应

输入图和多参考图示例

下面两个请求体使用 POST /v1/videos。图片使用服务端可直接下载的公网地址。参考图可通过提示词里的 [Image 1]、[Image 2] 对应至 input.media 中的顺序。

JSON
{
  "model": "happyhorse-1.0-i2v",
  "input": {
    "prompt": "让水面轻轻泛起涟漪,保持岸边景物静止。",
    "media": [{"type": "input_image", "url": "https://example.com/pond.jpg"}]
  },
  "parameters": {"resolution": "720P", "duration": 5, "watermark": false}
}
JSON
{
  "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 下载视频。

JSON
{
  "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
}

Happyhorse 参考文档

语音合成 TTS

#
本章目录
  • 接口:POST /v1/audio/speech
  • 返回内容为音频二进制,应按文件流保存
Bash
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.wav

qwen3-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 后,按相应扩展名保存响应。

Bash
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" 后,按相同格式命名文件。

Python
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"))

语音合成平台参考 · OpenAI Python 音频示例

实时语音识别

#
  • 协议: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 数据进行并行收发:

Bash
export ASR_API_KEY="$API_KEY"
export ASR_WS_URL="${BASE_URL/https:/wss:}/api-ws/v1/inference"
Python
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,可以先在本地运行:

Bash
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 个。

Bash
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 用量。

JSON
{
  "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 对象。

Python
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 和网格生成参数。
Bash
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 和网格生成参数。
Bash
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 数组;正面图片放在第一项,空视角使用空字符串。
Bash
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。
Bash
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 使用相同键和相同请求重试时会复用任务;相同键用于不同请求时返回 HTTP 409。
Bash
curl "$BASE_URL/v3/tasks/task_01JEXAMPLE3D" \
  -H "Authorization: Bearer $API_KEY"
JSON
{
  "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 对象。

JSON
{
  "model": "tripo-v3.1",
  "inputs": [
    {"front": "https://example.com/lantern/front.png"},
    {"left": {"url": "https://example.com/lantern/left.png"}}
  ],
  "model_seed": 17
}

位置数组须保留四个槽位,缺失视角填空字符串。下面提供正面、左侧和右侧图片。

JSON
{
  "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 失败时的错误码和解释,按可用字段处理。