客户对接文档

基础信息

所有接口均使用 HTTPS 调用。

支持模型

视频接口 model_id 可不传，不传时默认使用 Seedance 2.0。选择 Seedance 2.5 时请传 model_id: 67，选择 Wan 3.0 时请传 model_id: 69，选择 Seedance Fast 时请传 model_id: 51，选择 Happy Horse 时请传 model_id: 39。图片接口使用 model_id: 45。

鉴权方式

所有业务接口都需要在请求头中携带客户 API Key。请妥善保管 API Key，建议由服务端调用本 API。

Authorization: Bearer kc_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

1. 提交视频生成任务

请求参数

参考素材 URL 只能使用公网 HTTPS 地址。系统会拒绝 HTTP、localhost、内网/本地 IP、带账号密码的 URL，以及 DNS 解析到内网/本地地址的域名。模型 52/67/69 使用参考音频时，必须同时提供至少一张图片或一个视频。

计费规则

Seedance/Happy Horse: 消费金额 = seconds × count × 模型单价
Seedance 2.5: 480P ¥1.00/秒，720P ¥2.00/秒
Wan 3.0 上游积分/条 = ceil(seconds × 分辨率积分率)
Wan 3.0 消费金额 = count × 上游积分/条 × 1.25 ÷ 10 元
Wan 3.0 分辨率积分率: 480P = 1.5/秒，720P = 3/秒，1080P = 6/秒

余额不足时返回 402 Insufficient balance。上游失败、超时、业务错误码非 200 或生成接口没有返回 data.task_id 时，本次预扣金额会自动退回。

Seedance 2.0 请求示例

curl -X POST https://api.kuocai.net/api/v1/video/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 52,
    "prompt": "海边日落延时摄影，金色阳光洒在波浪上",
    "size": "9:16",
    "seconds": 5,
    "resolution": "720P",
    "count": 1,
    "reference_image": "https://your-cdn.example/reference.jpg"
  }'

Seedance 2.0 音视频参考请求示例

curl -X POST https://api.kuocai.net/api/v1/video/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 52,
    "prompt": "跟随参考视频节奏生成产品展示镜头",
    "size": "3:2",
    "seconds": 4,
    "resolution": "720P",
    "count": 1,
    "reference_image": "https://your-cdn.example/reference.jpg",
    "reference_audio": "https://your-cdn.example/reference.mp3",
    "reference_video": "https://your-cdn.example/reference.mp4"
  }'

Seedance 2.5 请求示例

curl -X POST https://api.kuocai.net/api/v1/video/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 67,
    "prompt": "人物在城市街道中自然行走，镜头平稳跟随",
    "size": "9:16",
    "seconds": 30,
    "resolution": "720P",
    "count": 1,
    "reference_images": [
      "https://your-cdn.example/reference-1.jpg",
      "https://your-cdn.example/reference-2.jpg"
    ],
    "reference_video": "https://your-cdn.example/reference.mp4"
  }'

Wan 3.0 请求示例

curl -X POST https://api.kuocai.net/api/v1/video/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 69,
    "prompt": "海边日落延时摄影，镜头沿海岸平稳推进",
    "size": "16:9",
    "seconds": 12,
    "resolution": "720P",
    "count": 1,
    "reference_image": "https://your-cdn.example/reference.jpg",
    "reference_audio": "https://your-cdn.example/reference.mp3"
  }'

Happy Horse 请求示例

curl -X POST https://api.kuocai.net/api/v1/video/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 39,
    "prompt": "草原上奔跑的马，电影感镜头",
    "size": "16:9",
    "seconds": 5,
    "resolution": "720P",
    "count": 2,
    "reference_images": [
      "https://your-cdn.example/horse-1.jpg",
      "https://your-cdn.example/horse-2.jpg"
    ]
  }'

Seedance Fast 请求示例

curl -X POST https://api.kuocai.net/api/v1/video/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 51,
    "prompt": "海边日落延时摄影，金色阳光洒在波浪上",
    "size": "9:16",
    "seconds": 8,
    "resolution": "480P",
    "count": 1,
    "reference_image": "https://your-cdn.example/reference.jpg",
    "reference_audio": "https://your-cdn.example/reference.mp3"
  }'

2. 提交图片生成任务

image2 采用异步任务模式。提交成功后使用返回的 task_id 查询生成结果。

请求参数

请求示例

curl -X POST https://api.kuocai.net/api/v1/images/generations \
  -H "Authorization: Bearer kc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": 45,
    "prompt": "自然光下的高端产品摄影，背景干净，细节清晰",
    "size": "1:1",
    "resolution": "1k",
    "count": 1,
    "reference_image": "https://your-cdn.example/reference.jpg"
  }'

提交成功示例

{
  "code": 200,
  "data": {
    "task_id": "01KQ2E96QH3XVMMBRGMFSR3Y6R",
    "model_id": 45,
    "model_name": "image2",
    "status": 0,
    "status_name": "已提交"
  }
}

3. 查询任务状态

task_id 为提交生成任务后返回的任务 ID。后续只能使用同一个 API Key 查询该任务结果。

curl -X GET https://api.kuocai.net/api/v1/tasks/T202604271430001234C001 \
  -H "Authorization: Bearer kc_your_api_key"

任务状态

建议客户服务端轮询查询任务状态。轮询间隔建议不少于 3-5 秒。

4. 查询账户用量和余额

该接口用于查询当前 API Key 的余额、消费金额、计费秒数/张数、任务历史和最近请求记录。

curl -X GET https://api.kuocai.net/api/v1/usage \
  -H "Authorization: Bearer kc_your_api_key"

5. 健康检查

该接口不需要客户 API Key，会返回当前可用模型列表。

curl https://api.kuocai.net/health

6. 客户页面

客户可打开自助页面查询余额，也可在测试台用自己的 kc_... API Key 直接测试 Seedance 2.0、Seedance 2.5、Wan 3.0、Seedance Fast、Happy Horse 和 image2。

https://api.kuocai.net/client
https://api.kuocai.net/test

错误码