API 说明文档

TokenFusion 平台 RESTful API 接入指南

产品介绍

TokenFusion 是统一的 AI 多模态 API 平台，面向内容创作、媒体生产与企业应用，提供文本对话、图像生成、视频生成与素材管理等能力。您只需使用平台 API Key，即可通过 OpenAI 兼容接口或平台标准接口调用模型广场中已开通的模型。

平台提供 AI 模型接口 与 管理接口 两大类 RESTful API。除生文流式模式返回 SSE 外，请求与响应均为 JSON。

接口分类

平台入门 · 登录开发者控制台

访问 控制台 > API Keys，创建 API 密钥并命名管理，支持一键复制 API Key。

鉴权认证

用 API Key 组装成 Authorization，填写到 Request Header 里，组装方式为：

代码块

Authorization: Bearer YOUR_API_KEY

其中 Bearer 与 API Key 之间需要保留一个空格。

• 生文、生图、生视频、素材库等模型调用接口须通过 Authorization Header 携带 API Key 进行鉴权。
• 素材库另要求当前用户已开通 火山（volcano） 类视频模型权限，否则返回 403。
• 余额查询接口使用账号和密码在请求体中认证，不需要传 Authorization Header。

API Key 无效、缺失或已禁用时返回 401，响应体为 {"detail":"..."}。

组装请求地址

平台统一接口地址格式如下：

代码块

https://api.xzzgm.cn/api/v1/

AI 模型接口路径示例：

https://api.xzzgm.cn/api/v1/chat/completions

https://api.xzzgm.cn/api/v1/images/generations

https://api.xzzgm.cn/api/v1/video/generations（视频 · Seedance）

https://api.xzzgm.cn/api/v1/kling/v1/videos/text2video（视频 · 可灵）

https://api.xzzgm.cn/api/v1/assets/{Action}（素材库；请求体字段为 PascalCase，见素材库章节）

管理接口路径示例：

https://api.xzzgm.cn/api/v1/user/balance

下文示例中的路径均相对于上述 Base URL。

完整请求示例（Seedance）

以下以 Seedance 文生视频为例，演示「创建任务 → 轮询查询 → 获取结果」的完整流程。可灵模型请使用可灵 接口，勿调用本节路径。

1. 创建视频生成任务

请求

curl -X POST https://api.xzzgm.cn/api/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田"
    }
  ],
  "ratio": "16:9",
  "duration": 5
}'

结果返回示例

{
  "id": "cgt-xxxx-xxxx"
}

2. 查询任务结果

提交异步任务后，使用返回的任务 ID 查询结果：

请求

curl -X GET "https://api.xzzgm.cn/api/v1/video/generations/${TASK_ID}" \
  -H "Authorization: Bearer YOUR_API_KEY"

结果返回示例

{
  "id": "cgt-xxxx-xxxx",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/xxxx/xxxx.mp4"
  },
  "usage": {
    "completion_tokens": 108900,
    "total_tokens": 108900
  },
  "created_at": 1779951506,
  "updated_at": 1779951777,
  "seed": 95020,
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "framespersecond": 24,
  "service_tier": "default",
  "generate_audio": true,
  "draft": false
}

任务进行中时 status 为 queued 或 running，请间隔 5~10 秒轮询，收到 429 时遵循 Retry-After 退避。

若需在视频中引用私域参考图/音视频，请先按下文 素材库 · Assets API 完成入库，再在 content 中使用 asset://{素材ID}。

接口总览

快速索引表；完整路径、参数与示例见左侧对应章节。模型类接口均使用 Authorization: Bearer API Key 鉴权。

文字 · Seed 生文

OpenAI 兼容的对话补全接口。使用 TokenFusion API Key 鉴权后，按 OpenAI 格式提交请求；平台校验模型权限并返回 JSON 或 SSE 流式响应。具体字段与扩展能力以模型广场中对应模型的说明为准。

能力模式对照

具体 Model ID 与能力标签以模型广场为准。须传入已上架且当前账户有权调用的 Model ID；否则返回 403，响应体为 {"detail":"无权调用该平台模型"}。

请求头（Request Headers）

请求体（Request Body）

下表为 OpenAI 兼容字段及部分多模态扩展。未在表中列出、但模型支持的扩展字段也可写入请求体。

messages 格式

content 可为字符串（纯文本），或多段对象数组（多模态理解）。

字符串 content（纯文本 / 默认对话）

{"role": "user", "content": "你好"}

多段 content（多模态）

messages[].content[] 中 type 常用取值如下（是否支持取决于所选模型）：

续写模式

在已有文本前缀基础上继续生成，适用于故事续写、代码补全等。将最后一条消息的 role 设为 assistant，content 填入希望模型接续的前缀，并在请求体设置 continue_final_message: true、add_generation_prompt: false。

{
  "role": "user",
  "content": "请以童话故事为主题续写：一片森林里，住着一只名叫小白的兔子。"
},
{
  "role": "assistant",
  "content": "有一天，小白"
}

响应（非流式）

HTTP 200，OpenAI 兼容 JSON。推理模型除 message.content 外，还可能返回 message.reasoning_content。

默认对话示例

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "doubao-seed-2-0-lite-260215",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "你好，有什么可以帮你？" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 10, "completion_tokens": 20, "total_tokens": 30 }
}

深度推理示例（含 reasoning_content）

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "最终给用户的回答……",
      "reasoning_content": "模型内部推理过程……"
    },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250 }
}

响应（流式 stream: true）

Content-Type 为 text/event-stream，每行 data: {...}，末尾 data: [DONE]。增量位于 choices[0].delta：

• delta.content：正文增量
• delta.reasoning_content：推理过程增量（深度推理时可能先输出此项，content 暂时为空）

客户端应同时监听两者，避免误判「长时间无输出」。设置 stream_options: {"include_usage": true} 可在末块获取 usage。

data: {"choices":[{"delta":{"reasoning_content":"……","content":""},"index":0}]}
data: {"choices":[{"delta":{"content":"你好"},"index":0}]}
data: [DONE]

常见错误

请求示例

默认对话（非流式）

curl -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-lite-260215",
    "messages": [
      {"role": "user", "content": "用一句话介绍 TokenFusion 平台"}
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

流式输出

curl -N -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "doubao-seed-2-0-lite-260215",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true,
    "stream_options": {"include_usage": true},
    "max_tokens": 512
  }'

续写模式

curl -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-lite-260215",
    "messages": [
      {"role": "user", "content": "请以童话故事为主题续写：一片森林里，住着一只名叫小白的兔子。"},
      {"role": "assistant", "content": "有一天，小白"}
    ],
    "continue_final_message": true,
    "add_generation_prompt": false,
    "max_tokens": 512,
    "temperature": 0.7
  }'

图片理解

curl -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-pro-260215",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请用一句话描述这张图片的主要内容"},
        {"type": "image_url", "image_url": {"url": "https://example.com/images/view.jpeg"}}
      ]
    }],
    "max_tokens": 256,
    "temperature": 0.2
  }'

视频理解

curl -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-pro-260215",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请用一句话概括这段视频在做什么"},
        {"type": "video_url", "video_url": {"url": "https://example.com/videos/sample.mp4"}}
      ]
    }],
    "max_tokens": 256,
    "temperature": 0.2
  }'

音频理解（input_audio）

curl -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-lite-260428",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "请用一句话描述这段音频的内容或氛围"},
        {"type": "input_audio", "input_audio": {"data": "BASE64_AUDIO_DATA", "format": "mp3"}}
      ]
    }],
    "max_tokens": 256,
    "temperature": 0.2
  }'

input_audio.data 为音频文件 Base64（不含 Data URI 前缀）；format 常用 mp3、wav。建议用 SDK 或脚本构造请求体。

深度推理

curl -X POST https://api.xzzgm.cn/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-lite-260215",
    "messages": [{
      "role": "user",
      "content": "一个农夫需要把狼、羊、白菜运过河，船每次只能载一样。狼不能和羊单独在一起，羊不能和白菜单独在一起。请给出可行步骤并说明理由。"
    }],
    "reasoning_effort": "high",
    "max_tokens": 1024,
    "temperature": 0.2
  }'

业务错误通常以 OpenAI 兼容的 error 对象返回；平台鉴权与权限错误以 detail 字段返回。

图像 · Seedream 生图

OpenAI 兼容的图像生成接口。使用 TokenFusion API Key 鉴权，按 OpenAI 格式提交请求；平台校验模型权限并返回 JSON 或 SSE 流式响应。

部分图像模型支持扩展参数（如 image、sequential_image_generation、tools 等），是否可用以模型广场中对应模型说明为准。

能力模式对照

具体 Model ID 以模型广场实时列表为准。须传入已上架且当前账户有权调用的 Model ID；传 model 时若无权调用，返回 403，响应体为 {"detail":"无权调用该平台模型"}。

请求头（Request Headers）

请求体（Request Body）

下表包含 OpenAI 兼容字段及部分模型扩展字段。未在表中列出、但模型支持的扩展字段也可写入请求体。

参考图（image）约束

• 格式：jpeg、png；Seedream 5.0 / 4.5 / 4.0 另支持 webp、bmp、tiff、gif
• 单张大小：不超过 10 MB；请求体总大小不超过 64 MB（大文件请用 URL，勿 Base64）
• 宽高比：Seedream 4.5 / 4.0 / 5.0 均为 [1/16, 16]；宽高像素 > 14，总像素 ≤ 6000×6000
• 数量：最多 14 张参考图；组图时参考图数 + 输出张数 ≤ 15

size 与分辨率（Seedream）

也可在 prompt 中用自然语言描述宽高比，配合 size: "2K" 由模型决定具体像素。

响应（非流式）

成功响应示例（Seedream 4.5 文生图）

{
  "model": "doubao-seedream-4-5-251128",
  "created": 1780281542,
  "data": [
    {
      "url": "https://example.com/generated.jpeg",
      "size": "2560x1440"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16280,
    "total_tokens": 16280
  }
}

联网搜索成功时，usage 可能包含 tool_usage.web_search 计数（Seedream 5.0）。

响应（流式 stream: true）

Content-Type 为 text/event-stream。每张图片生成完成后推送 image_generation.partial_succeeded，全部结束后推送 image_generation.completed，末尾为 data: [DONE]（仅部分支持流式的模型）。

event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"doubao-seedream-4-5-251128","image_index":0,"url":"https://..."}

event: image_generation.completed
data: {"type":"image_generation.completed","usage":{"generated_images":1,"output_tokens":16280,"total_tokens":16280}}

data: [DONE]

请求示例

文生图

curl -X POST https://api.xzzgm.cn/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "一只在窗台上晒太阳的橘猫，写实摄影风格，柔和自然光",
    "size": "2K",
    "watermark": false
  }'

图生图

curl -X POST https://api.xzzgm.cn/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "保持人物姿势不变，将服装材质改为透明清水，光影从反射变为折射",
    "image": "https://example.com/images/seedream4_5_imageToimage.png",
    "size": "2K",
    "watermark": false
  }'

多图融合

curl -X POST https://api.xzzgm.cn/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "将图1的服装换为图2的服装，保持图1的人物姿态",
    "image": [
      "https://example.com/images/seedream4_imagesToimage_1.png",
      "https://example.com/images/seedream4_5_imagesToimage_2.png"
    ],
    "sequential_image_generation": "disabled",
    "size": "2K",
    "watermark": false
  }'

多参考图生组图

curl -X POST https://api.xzzgm.cn/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "参考图1人物与图2服装风格，生成一组连贯时尚穿搭展示图",
    "image": [
      "https://example.com/images/seedream4_imagesToimage_1.png",
      "https://example.com/images/seedream4_5_imagesToimage_2.png"
    ],
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 3},
    "size": "2K",
    "watermark": false
  }'

流式输出

curl -X POST https://api.xzzgm.cn/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "doubao-seedream-4-5-251128",
    "prompt": "一只在窗台上晒太阳的橘猫，写实摄影风格",
    "size": "2K",
    "stream": true,
    "watermark": false
  }'

联网搜索（仅 Seedream 5.0）

curl -X POST https://api.xzzgm.cn/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "根据当前流行的时装周街拍趋势，生成一张都市时尚街拍照片，自然光，高清",
    "tools": [{"type": "web_search"}],
    "size": "2K",
    "watermark": false
  }'

业务错误通常以 OpenAI 兼容的 error 对象返回；平台鉴权与权限错误以 detail 字段返回。

视频 · Seedance

面向模型广场中的 Seedance 系列视频模型，提供异步创建、查询与取消。请求体使用 model + content 统一格式；成功创建后返回任务 ID，需轮询查询接口获取视频 URL。素材库 asset:// 仅适用于本节；完整字段说明见在线产品手册（需登录且已授权）。

创建任务

请求体（Request Body）

Content 数组对象

文本对象

{ "type": "text", "text": "描述期望生成的视频内容" }

图片对象

{
  "type": "image_url",
  "image_url": { "url": "https://example.com/frame.jpg" },
  "role": "first_frame"
}

role 可选：first_frame（首帧）、last_frame（尾帧）、reference_image（参考图）。也支持 asset://{素材ID} 引用平台素材库（须为当前用户拥有的素材）。

响应

结果返回示例

{ "id": "cgt-2025xxxxxx-xxxx" }

仅返回任务 ID，不包含视频 URL。

查询任务

查询任务状态与结果。仅可查询当前 API Key 所属用户创建的任务。平台对同一任务有进程内查询缓存与最小间隔限制，轮询过快返回 429（响应头含 Retry-After）。

路径参数

响应字段

请求示例

请求

curl https://api.xzzgm.cn/api/v1/video/generations/cgt-2025xxxxxx-xxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

取消任务

取消排队中的任务。仅 queued 状态可取消；响应结构与查询接口相同，返回取消后的任务状态。

请求

curl -X POST https://api.xzzgm.cn/api/v1/video/generations/cgt-2025xxxxxx-xxxx/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

素材库

面向火山方舟（Volcano Ark）素材库的统一代理接口：将图片、视频、音频等参考素材入库后，在 POST /video/generations 的 content 中通过 asset://{素材ID} 引用。平台使用服务端 AK/SK 访问上游，下游仅需 TokenFusion API Key，不可在 URL 中指定上游账号（如 ?account=...）。

通用规则

推荐流程

1. CreateAssetGroup — 创建素材组，记录 Result.Id
2. CreateAsset — 提交公网可访问素材 URL，记录素材 Result.Id
3. GetAsset — 每 3~5 秒轮询直至 Status 为 Active
4. POST /video/generations — 在 content 的 image_url.url / video_url.url / audio_url.url 中填写 asset://{素材ID}

Action 列表

以下操作均为 POST，路径中的 {Action} 与表内名称一致。

请求头

通用字段

创建素材组 · CreateAssetGroup

POST https://api.xzzgm.cn/api/v1/assets/CreateAssetGroup

请求

curl -X POST https://api.xzzgm.cn/api/v1/assets/CreateAssetGroup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Name": "brand-hero-v1",
  "Description": "品牌主视觉素材组",
  "GroupType": "AIGC",
  "ProjectName": "default"
}'

响应示例

{
  "Result": {
    "Id": "group-202604020001"
  }
}

创建素材 · CreateAsset

POST https://api.xzzgm.cn/api/v1/assets/CreateAsset

成功仅表示已提交预处理队列；新素材默认 Processing，须轮询 GetAsset 至 Active 后再用于生视频。图片/视频/音频的格式与大小限制以火山方舟素材库文档为准。

请求

curl -X POST https://api.xzzgm.cn/api/v1/assets/CreateAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "GroupId": "group-202604020001",
  "URL": "https://example.com/hero-face.png",
  "Name": "hero-face-closeup",
  "AssetType": "Image",
  "ProjectName": "default"
}'

响应示例

{
  "Result": {
    "Id": "asset-202604020001"
  }
}

查询素材 · GetAsset

POST https://api.xzzgm.cn/api/v1/assets/GetAsset

curl -X POST https://api.xzzgm.cn/api/v1/assets/GetAsset \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Id": "asset-202604020001",
  "ProjectName": "default"
}'

响应示例（可用）

{
  "Result": {
    "Id": "asset-202604020001",
    "Name": "hero-face-closeup",
    "URL": "https://example-cdn.com/asset/hero-face.png",
    "AssetType": "Image",
    "GroupId": "group-202604020001",
    "Status": "Active",
    "ProjectName": "default",
    "CreateTime": "2026-04-02T09:03:00Z",
    "UpdateTime": "2026-04-02T09:03:20Z"
  }
}

Result.URL 通常短期有效，请及时用于下载或生视频；入库轮询建议间隔 3~5 秒。

列表与其它操作

ListAssets — 仅返回当前用户拥有的素材；Filter.GroupType 必填 AIGC，可按 GroupIds、Statuses、Name 过滤。

ListAssets 请求示例

curl -X POST https://api.xzzgm.cn/api/v1/assets/ListAssets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Filter": {
    "GroupIds": ["group-202604020001"],
    "GroupType": "AIGC",
    "Statuses": ["Active"]
  },
  "PageNumber": 1,
  "PageSize": 20,
  "SortBy": "CreateTime",
  "SortOrder": "Desc",
  "ProjectName": "default"
}'

ListAssetGroups、GetAssetGroup、UpdateAssetGroup、UpdateAsset、DeleteAsset 路径分别为 /assets/{Action}，请求体字段与火山方舟 Assets API 一致，由平台透传并维护本地归属记录。

在生视频中引用素材

素材 Status 为 Active 后，在创建 Seedance 视频任务时使用 asset:// 前缀（须为当前用户拥有的素材 ID）：

curl -X POST https://api.xzzgm.cn/api/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "人物在花海中缓慢转身"},
    {
      "type": "image_url",
      "image_url": {"url": "asset://asset-202604020001"},
      "role": "reference_image"
    }
  ],
  "ratio": "16:9",
  "duration": 5
}'

提示词中建议用「图片1」「视频1」等顺序指代参考素材，勿将裸 Asset ID 写入提示词正文。仅支持素材引用的火山视频模型可使用 asset://；可灵等其它上游不支持此引用方式。

素材库常见错误

部分上游业务错误会以原 HTTP 状态码与响应体透传，平台不做二次包装。更完整的 Seedance 2.0 字段说明见在线产品手册。

视频 · 可灵

面向模型广场中的可灵（Kling）系列视频模型。请使用 /kling/v1/... 路径及本章示例字段。覆盖文生/图生视频、Omni 视频（多模态参考生视频）、动作控制、对口型、数字人、音效、语音合成、自定义音色等能力（以模型广场及账户授权为准）。

创建任务时可在 body 中传 callback_url；任务进入终态后平台推送 video.task.updated 事件（与 Seedance 回调格式一致），常见字段含 task_id、task_status、task_result.videos 等。

通用响应结构

创建（POST） 成功时 data 常见字段：

查询（GET） 终态成功时 data.task_result 常见字段：

查询路径参数 {task_id} 可与创建返回的 task_id 或 external_task_id 二选一填入（须与创建类型路径一致）。

轮询间隔建议 5–10 秒；过快可能 429。查询路径必须与创建时一致（如文生用 text2video，不可用 image2video 路径查）。

文生视频

官方文档：Text to Video。请求头须含 Content-Type: application/json 与 Authorization: Bearer <API_KEY>。

请求体

camera_control 子字段

请求示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/text2video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model_name": "kling-v3",
  "prompt": "写实风格，晴朗蓝天下的白色雏菊花田",
  "duration": "5",
  "aspect_ratio": "16:9",
  "mode": "pro",
  "sound": "on"
}'

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "task_id": "kling-task-xxxx",
    "task_status": "submitted"
  }
}

curl https://api.xzzgm.cn/api/v1/kling/v1/videos/text2video/kling-task-xxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

图生视频

官方文档：Image to Video。

请求体

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/image2video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model_name": "kling-v3",
  "prompt": "让画面中的人物轻轻转头",
  "image": "https://example.com/first-frame.png",
  "duration": "5"
}'

curl https://api.xzzgm.cn/api/v1/kling/v1/videos/image2video/kling-task-yyyy \
  -H "Authorization: Bearer YOUR_API_KEY"

Omni 视频

统一多模态生视频接口，路径与可灵官方 Omni Video 一致：POST /v1/videos/omni-video。适用模型如 kling-v3-omni、kling-video-o1（以模型广场授权为准）。

能力概览（单接口覆盖多种场景）：

• 文生视频：仅 prompt
• 图生视频：image_list 首帧 / 首尾帧（first_frame、end_frame）
• 视频编辑：video_list 且 refer_type: "base"（成片时长跟随参考视频）
• 特征参考视频：video_list 且 refer_type: "feature"（风格/动作参考）
• 主体驱动：element_list 引用已有或 inline 创建的主体
• 多镜头分镜：multi_shot + multi_prompt
• 原生有声：sound: "on"（与参考视频同时使用时须 sound: "off"）

提示词引用语法

在 prompt 中用占位符关联参考素材（序号与列表顺序一致，从 1 开始）：

请求体

image_list[] 参考图

video_list[] 参考视频

element_list[] 主体引用

三种方式可混用：

示例 1 · 纯文生视频

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/omni-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model_name": "kling-v3-omni",
  "prompt": "金色柴犬在阳光草地上慢镜头奔跑，电影感",
  "mode": "pro",
  "duration": "5",
  "aspect_ratio": "16:9",
  "sound": "off"
}'

示例 2 · 图参考（占位符）

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/omni-video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model_name": "kling-v3-omni",
  "prompt": "参考 <<<image_1>>>，人物向镜头微笑挥手",
  "image_list": [
    { "image_url": "https://example.com/ref.jpg" }
  ],
  "duration": "5",
  "aspect_ratio": "16:9",
  "mode": "std",
  "sound": "off"
}'

示例 3 · 首尾帧图生视频

{
  "model_name": "kling-v3-omni",
  "prompt": "从白天到夜晚的城市天际线，灯光逐渐亮起",
  "mode": "pro",
  "duration": "5",
  "sound": "off",
  "image_list": [
    { "image_url": "https://example.com/day.jpg", "type": "first_frame" },
    { "image_url": "https://example.com/night.jpg", "type": "end_frame" }
  ]
}

示例 4 · 视频编辑（refer_type: base）

{
  "model_name": "kling-v3-omni",
  "prompt": "为画面添加飘雪与冷色调",
  "mode": "pro",
  "aspect_ratio": "16:9",
  "sound": "off",
  "video_list": [
    {
      "video_url": "https://example.com/original.mp4",
      "refer_type": "base",
      "keep_original_sound": "yes"
    }
  ]
}

示例 5 · 多镜头分镜

{
  "model_name": "kling-v3-omni",
  "multi_shot": true,
  "shot_type": "customize",
  "duration": "10",
  "aspect_ratio": "16:9",
  "mode": "pro",
  "sound": "off",
  "multi_prompt": [
    { "index": 1, "prompt": "城堡远景日出 Establishing shot", "duration": "5" },
    { "index": 2, "prompt": "骑士拔剑特写", "duration": "5" }
  ]
}

响应示例（创建）

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_xxxxxxxx",
    "task_status": "submitted"
  }
}

响应示例（查询成功）

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_xxxxxxxx",
    "task_status": "succeed",
    "task_result": {
      "videos": [
        {
          "id": "825406034503692376",
          "url": "https://...",
          "duration": "5.0"
        }
      ]
    }
  }
}

curl https://api.xzzgm.cn/api/v1/kling/v1/videos/omni-video/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

动作控制

官方文档：Motion Control。将人物参考图与动作参考视频结合生成视频；成片时长跟随参考视频。

请求体

请求示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/motion-control \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model_name": "kling-v3",
  "image_url": "https://example.com/person.jpg",
  "video_url": "https://example.com/dance-reference.mp4",
  "prompt": "人物按参考视频动作跳舞",
  "mode": "pro",
  "keep_original_sound": "yes",
  "character_orientation": "video"
}'

对口型

官方文档：Lip-Sync。两步流程：

1. POST /kling/v1/videos/identify-face（同步）→ 获得 session_id、face_id 列表
2. POST /kling/v1/videos/advanced-lip-sync（异步）→ 轮询 GET .../advanced-lip-sync/{task_id}

identify-face 请求体（同步）

同步接口：立即返回人脸分析结果，成功即计费。session_id 供对口型使用。

advanced-lip-sync 请求体（异步）

face_choose[] 项

identify-face 响应示例

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "session_id": "session_xxxxxxxx",
    "face_data": [
      { "face_id": "face_01", "face_image": "https://..." }
    ]
  }
}

advanced-lip-sync 请求示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/advanced-lip-sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "session_id": "session_xxxxxxxx",
  "face_choose": [
    {
      "face_id": "face_01",
      "audio_id": "825455158141661278",
      "sound_start_time": 0,
      "sound_end_time": 5000,
      "sound_insert_time": 0,
      "sound_volume": 1.0,
      "original_audio_volume": 0.5
    }
  ]
}'

数字人

官方文档：Avatar。路径为 /videos/avatar/image2video（非顶层 image2video）。

请求体

请求示例（TTS 驱动）

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/videos/avatar/image2video \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image": "https://example.com/portrait.jpg",
  "audio_id": "825455158141661278",
  "prompt": "人物面向镜头自然说话",
  "mode": "std"
}'

请求示例（音频 URL 驱动）

{
  "image": "https://example.com/portrait.jpg",
  "sound_file": "https://example.com/speech.mp3",
  "prompt": "人物面向镜头自然说话",
  "mode": "pro"
}

响应示例（查询成功）

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_xxxxxxxx",
    "task_status": "succeed",
    "task_result": {
      "videos": [
        { "id": "825455158141661278", "url": "https://...", "duration": "5.0" }
      ]
    }
  }
}

语音合成（TTS）

官方文档：TTS。同步接口：一次请求返回合成结果，成功即计费。task_result.audios[0].id 可作为 audio_id 用于数字人、对口型。

请求体

请求示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/audio/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "你好，欢迎使用 TokenFusion。",
  "voice_id": "genshin_vindi2",
  "voice_language": "zh",
  "voice_speed": "1.0"
}'

响应示例

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_tts_xxxx",
    "task_status": "succeed",
    "task_result": {
      "audios": [
        {
          "id": "825455158141661278",
          "url": "https://...",
          "duration": "3.2"
        }
      ]
    }
  }
}

数字人、对口型等场景使用 task_result.audios[0].id 作为 audio_id。

文生音效

官方文档：Text to Audio。异步：创建后轮询同路径 GET 直至 task_status 为 succeed。

请求体

请求示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/audio/text-to-audio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "清晨鸟鸣与微风声",
  "duration": 7.0
}'

响应示例（查询成功）

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_audio_xxxx",
    "task_status": "succeed",
    "task_result": {
      "audios": [
        { "id": "...", "url": "https://...", "duration": "7.0" }
      ]
    }
  }
}

curl https://api.xzzgm.cn/api/v1/kling/v1/audio/text-to-audio/task_audio_xxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

视频生音效

官方文档：Video to Audio。为视频生成匹配音效/配乐（异步）。

请求体

请求示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/audio/video-to-audio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "video_id": "825406034503692376",
  "sound_effect_prompt": "与画面氛围匹配的环境音效",
  "bgm_prompt": "轻柔的钢琴背景",
  "asmr_mode": false
}'

响应示例（查询成功）

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_status": "succeed",
    "task_result": {
      "audios": [
        { "url": "https://...", "duration": "5.0" }
      ]
    }
  }
}

curl https://api.xzzgm.cn/api/v1/kling/v1/audio/video-to-audio/task_v2a_xxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

自定义音色

官方文档：Custom Voices。从人声样本或历史视频提取音色（异步创建 + 轮询）。

创建请求体（custom-voices）

删除请求体（delete-voices）

创建示例

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/general/custom-voices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "voice_name": "my-brand-voice",
  "voice_url": "https://example.com/clean-voice-sample.wav"
}'

查询成功响应（节选）

{
  "code": 0,
  "data": {
    "task_status": "succeed",
    "task_result": {
      "voices": [
        { "voice_id": "829877809978941442", "voice_name": "my-brand-voice" }
      ]
    }
  }
}

删除音色（不计费）

curl -X POST https://api.xzzgm.cn/api/v1/kling/v1/general/delete-voices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "829877809978941442"}'

删除接口 body 仅需 voice_id；创建类接口轮询路径为 GET /kling/v1/general/custom-voices/{id}，{id} 为创建返回的 task/资源 ID。

管理接口 · 查询余额

客户可使用平台登录账号和密码查询账户余额。账号即注册邮箱。该接口不会创建登录会话，也不会返回 API Key 或访问令牌；请不要将密码放入 URL Query。

请求体

响应体

请求示例

请求

curl -X POST https://api.xzzgm.cn/api/v1/user/balance \
  -H "Content-Type: application/json" \
  -d '{
    "account": "user@example.com",
    "password": "YourLoginPassword1"
  }'

响应示例

结果返回示例

{
  "account": "user@example.com",
  "balance": 100.0,
  "reserved_balance": 12.5,
  "available_balance": 87.5
}

模型能力支持

下列列表展示当前账户在模型广场中可见的模型（未登录时展示平台已上架模型）。完整能力说明、参数约束与价格请前往模型广场查看；调用前请确认 Model ID 与您的账户授权一致。

文字 · Seed 生文

图像 · Seedream 生图

视频 · Seedance 模型

下列模型请使用 /video/generations，见 视频 · Seedance。

视频 · 可灵模型

下列模型请使用 /kling/v1/...，见 视频 · 可灵。

产品与计费

文字 · Seed 生文

• 按模型用量（通常为 token）计费，费用从平台账户余额实时扣除。
• 具体单价与计费档位以模型广场及控制台说明为准。

图像 · Seedream 生图

• 按模型规则计费（可能按张、按 token 或其他单位），费用从平台账户余额扣除。
• 具体单价以模型广场及控制台说明为准。

视频 · Seedance

• 创建任务前按模型定价规则预冻结可用余额；可用余额不足返回 402。
• 任务进入终态后自动结算：释放冻结；成功时主要依据 usage.total_tokens 与模型单价规则实扣。
• 不同模型、分辨率、是否含视频输入等条件可能匹配不同价格规则。

视频 · 可灵

• 通过 /kling/v1/... 调用时，预冻结按模型版本（mode）、时长（duration）、是否开声音（sound）等维度匹配平台计费规则。
• 异步任务成功后按 TokenFusion 平台结算价实扣（与预冻结金额可能略有差异）；失败不扣费，仅释放冻结。
• 同步接口（TTS、人脸识别）在请求成功时立即结算；删除类接口不计费。
• 价目与规则说明以模型广场及控制台为准。

素材库（Assets）

• 素材组/素材的创建、查询、更新、删除接口不单独向用户计费；上游费用由平台配置的火山素材库账号承担。
• 素材入库本身不产生 TokenFusion 视频预冻结；通过 asset:// 引用参与 Seedance 生视频时，仍按对应 Seedance 模型规则预冻结与结算。

余额查询

管理接口返回的 available_balance 可用于判断视频任务是否可创建。

错误与状态码

集成建议

1. 生文流式：设置 stream: true，按 SSE 规范解析 data: 行；深度推理时同时监听 delta.reasoning_content 与 delta.content。
2. 生文续写：末条 assistant 消息填前缀，并设 continue_final_message: true、add_generation_prompt: false。
3. 生文多模态：图片/视频用 Pro 模型；音频理解优先 doubao-seed-2-0-lite-260428，勿在 Chat 中使用 audio_url。
4. 生图流式：设置 stream: true 并传 Accept: text/event-stream；监听 image_generation.partial_succeeded 逐张渲染，以 data: [DONE] 结束。
5. 生图模式选型：文生图/图生图/融合/组图通过 image 与 sequential_image_generation 组合切换；联网搜索须使用 Seedream 5.0（doubao-seedream-5-0-260128）。
6. 视频选型：Seedance 用 /video/generations，可灵用 /kling/v1/...；详见接口分类。
7. Seedance 异步流程：创建任务后每 5~10 秒轮询查询；收到 429 时遵循 Retry-After 退避。
8. 可灵：请求体字段以可灵章节示例为准；迁移时通常只需替换 Base URL 与 API Key。
9. 素材入库：仅配合 Seedance；CreateAsset 后轮询 GetAsset 至 Active，再在 content 中用 asset://；素材库用 PascalCase，生视频用小写字段。
10. 及时转存：视频、生图与素材库返回的 URL 通常有时效（生图 URL 约 24 小时），请在成功后尽快下载到自有存储。
11. 错误处理：区分平台鉴权/权限错误（detail）与 OpenAI 兼容格式的模型业务错误（error 对象）；生图 503 model_not_found 多为 Model ID 未在模型广场绑定渠道。
12. 余额监控：视频业务建议定期调用余额查询接口或关注控制台用量页。
13. 模型选型：以模型广场实时列表为准，勿硬编码已下线或未接入的 Model ID。