客户对接文档

基础信息

所有接口均使用 HTTPS 调用。

支持模型

视频接口 model_id 可不传，不传时默认使用 Seedance。选择 Seedance Fast 时请传 model_id: 51，选择 Seedance 标准线路一时请传 model_id: 53，选择 Happy Horse 时请传 model_id: 39。图片接口选择 fengling image2 时请传 model_id: 45。

鉴权方式

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

Authorization: Bearer kc_xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

1. 提交视频生成任务

请求参数

参考素材 URL 只能使用公网 HTTPS 地址。系统会拒绝 HTTP、localhost、内网/本地 IP、带账号密码的 URL，以及 DNS 解析到内网/本地地址的域名。

计费规则

消费金额 = seconds × count × 模型单价

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

Seedance 请求示例

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": 4,
    "resolution": "480P",
    "count": 1,
    "reference_video": "https://your-cdn.example/reference.mp4"
  }'

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

Seedance 标准线路一请求示例

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": 53,
    "prompt": "城市夜景航拍，霓虹灯反射在雨后街道上",
    "size": "16:9",
    "seconds": 8,
    "resolution": "720P",
    "count": 1,
    "reference_image": "https://your-cdn.example/reference.jpg"
  }'

2. 提交图片生成任务

fengling image2 售价为 ¥0.30/张，成本为 ¥0.10/张。计费公式为 count × ¥0.30。

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": "2K",
    "count": 3,
    "reference_images": [
      "https://your-cdn.example/cat-1.jpg",
      "https://your-cdn.example/cat-2.jpg"
    ]
  }'

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、Seedance Fast、Seedance 标准线路一、Happy Horse 和 fengling image2。

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

错误码