惊鸿开发者 API

开始接入

API v1

接口基址与认证

登录惊鸿后点击顶部“API Key”，为每个调用方创建独立 Key。密钥仅在创建时完整显示一次，请妥善保存，不要放在浏览器前端代码中。

Base URL: https://jinghong.asia
Authorization: Bearer sk_jh_xxx
Content-Type: application/json

推荐调用顺序

先查询模型与素材限制；有参考素材时上传文件；然后创建视频任务并轮询任务状态。

GET  /v1/models
POST /v1/files                    # 可选
POST /v1/video/generations
GET  /v1/video/generations/:id

查询模型

GET /v1/models

curl https://jinghong.asia/v1/models \
  -H "Authorization: Bearer sk_jh_xxx"

每个模型会返回清晰度、支持时长、画面比例、积分价格与素材数量限制。支持真人的模型还会返回 supports_real_people。提交任务前应以实时返回值为准。西梅线路还会返回音视频合计限制、参考素材时长限制和桔子线路的提示词长度限制。

{
  "id": "bf-sdas-2.0",
  "name": "BF Seedance 2.0 · 720P",
  "resolution": "720p",
  "durations": ["4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"],
  "blocks_real_people": false,
  "aspect_ratios": ["9:16", "16:9", "1:1"],
  "max_runs": 1,
  "reference_limits": { "image": 9, "audio": 3, "video": 3, "total": 15 },
  "supports_real_people": true,
  "points": 0.6,
  "billing_mode": "per_second"
}

上传参考素材

POST /v1/files

使用 multipart/form-data，文件字段名必须为 file，单文件最大 55 MB。也可以跳过此接口，在创建任务时直接提供调用方自己的公网 HTTPS 素材 URL。

curl https://jinghong.asia/v1/files \
  -X POST \
  -H "Authorization: Bearer sk_jh_xxx" \
  -F "file=@reference.png"

{
  "id": "asset_xxx",
  "object": "file",
  "kind": "image",
  "filename": "reference.png",
  "url": "https://...",
  "upstream_id": "file_xxx"
}

创建视频

POST /v1/video/generations

curl https://jinghong.asia/v1/video/generations \
  -X POST \
  -H "Authorization: Bearer sk_jh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bf-sdas-2.0",
    "prompt": "电影感竖屏短视频，人物看向镜头 @人物",
    "duration": "10",
    "aspect_ratio": "9:16",
    "runs": 1,
    "references": [
      { "kind": "image", "name": "人物.png", "url": "https://example.com/person.png" },
      { "kind": "audio", "name": "旁白.mp3", "url": "https://example.com/voice.mp3", "durationSeconds": 8 }
    ]
  }'

references 支持 image、audio、video。每类数量及合计数量不能超过所选模型的 reference_limits；西梅线路的音频和视频还需要填写 durationSeconds，并遵守 reference_duration_limits。runs 不能超过 max_runs。超过限制时接口返回 400 且不会扣积分。runs 大于 1 时会创建多个独立任务。

另一种素材 URL 写法

{
  "imageUrls": ["https://example.com/1.png"],
  "audioUrls": ["https://example.com/voice.mp3"],
  "videoUrls": ["https://example.com/reference.mp4"]
}

创建成功响应

{
  "id": "task_xxx",
  "status": "queued",
  "model": "bf-sdas-2.0",
  "cost": 6,
  "video_url": null,
  "progress": 0,
  "failure_reason": null,
  "count": 1,
  "total_cost": 6,
  "task_ids": ["task_xxx"],
  "tasks": [{ "id": "task_xxx", "status": "queued", "cost": 6 }],
  "created_at": "2026-07-23T00:00:00.000Z"
}

查询任务

GET /v1/video/generations/:id

curl https://jinghong.asia/v1/video/generations/task_xxx \
  -H "Authorization: Bearer sk_jh_xxx"

status 可能为 queued、running、completed、failed 或 canceled。completed 时 video_url 为结果地址；failed 时查看 failure_reason。

积分与退款

per_second 模型按“单价 × 时长 × 生成数量”扣费，per_request 模型按“单价 × 生成数量”扣费。创建任务时扣除积分；上游生成失败会自动原路退回本次积分。

常见状态码

400  参数、模型或参考素材数量不符合要求
401  API Key 无效或已撤销
402  账号积分不足
404  任务不存在，或任务不属于当前 Key 的账号
413  上传文件超过 55 MB
500/502  服务或上游暂时异常