惊鸿开发者 API

快速开始

API v1 · 网站 5.7.78

接口基址与认证

在惊鸿网站登录后，通过顶部“API Key”创建密钥。每个调用方应使用独立 Key；密钥仅在创建时完整显示一次，不要写入浏览器前端代码。

标准基址：https://jinghong.asia/v1
兼容基址：https://jinghong.asia/api/v1
请求头：Authorization: Bearer sk_jh_xxx

/api/v1/* 会兼容映射到相同的 /v1/* 视频接口。本文示例统一使用标准基址。

推荐调用顺序

GET  /v1/models                       # 查询当前账号可用模型
POST /v1/files                        # 有参考素材时上传，可选
POST /v1/video/generations            # 标准方式创建任务
GET  /v1/video/generations/:id        # 查询标准任务

POST /v1/videos                       # 第三方/OpenAI 风格兼容创建
GET  /v1/videos/:id                   # 查询兼容任务
GET  /v1/videos/:id/content           # 预览或下载完成的视频
HEAD /v1/videos/:id/content           # 检查视频是否可读取

账号权限

GET /v1/models 只返回当前 API Key 所属账号能够使用且已经上架的模型。管理员设为“指定客户可见”的模型，只会返回给已授权账号；未授权账号不能查询或创建该模型的任务。

查询可用模型

先调用此接口

GET /v1/models

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

模型上下架、账号授权、价格和素材限制都可能由管理员调整。创建任务前应读取实时返回值，不要在客户端写死模型清单。

{
  "object": "list",
  "data": [{
    "id": "sudashui-xg-sd2.5-900-720p",
    "object": "model",
    "name": "SDAS Seedance 2.5 · 900 · 720P",
    "owned_by": "速达水 API",
    "resolution": "720p",
    "supports_real_people": true,
    "blocks_real_people": false,
    "durations": ["4", "5", "6", "...", "30"],
    "aspect_ratios": ["1:1", "3:4", "4:3", "9:16", "16:9", "21:9"],
    "max_runs": 1,
    "reference_limits": { "image": 9, "audio": 0, "video": 0, "total": 9 },
    "max_prompt_characters": 5000,
    "points": 4.5,
    "billing_mode": "per_request"
  }]
}

常用返回字段

durations 是允许的秒数；aspect_ratios 是允许的比例；max_runs 是单次请求最多生成数量；reference_limits 是图片、音频、视频及总素材上限；points 与 billing_mode 共同决定扣费方式。

上传参考素材

可选

POST /v1/files

使用 multipart/form-data，文件字段名必须为 file，单文件最大 55 MB。必须通过 X-Jinghong-Upstream-Provider 指定目标模型所属渠道，以便素材上传到正确的上游。

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

{
  "id": "asset_xxx",
  "object": "file",
  "kind": "image",
  "filename": "reference.png",
  "bytes": 102400,
  "url": "https://...",
  "upstream_id": "file_xxx",
  "created_at": "2026-09-19T00:00:00.000Z"
}

支持的渠道标识

sudashui  sudashui_ll  megaby  ximei  d1  ailing  manyan
hongniao  aicost  lingdong  buming  xiaopei  qingying
openvideo  sensaudio_pool

也可以不调用上传接口，直接在创建任务时提交调用方自己的可公网访问 HTTPS 素材地址。素材地址必须能被目标上游下载，临时链接过期后会导致任务失败。

标准方式创建视频

支持多发

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": "sudashui-xg-sd2.5-900-720p",
    "prompt": "电影感竖屏短视频，人物看向镜头 @人物",
    "duration": "15",
    "aspect_ratio": "9:16",
    "runs": 1,
    "references": [
      {
        "kind": "image",
        "name": "人物.png",
        "url": "https://example.com/person.png",
        "size": 102400
      }
    ]
  }'

model、prompt 为必填项。duration、aspect_ratio、runs 与参考素材必须符合所选模型的实时限制；超过限制会返回 400 且不扣积分。runs 大于 1 时会创建多个互相独立的任务，但不能超过模型返回的 max_runs。

参考素材的两种写法

references 支持 image、audio、video。当模型返回素材时长或大小限制时，音视频应提供 durationSeconds，素材应提供 size（字节，也兼容 bytes）。也可以使用下面的简写：

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

创建成功：HTTP 201

{
  "id": "task_xxx",
  "status": "queued",
  "model": "sudashui-xg-sd2.5-900-720p",
  "cost": 4.5,
  "video_url": null,
  "progress": 0,
  "failure_reason": null,
  "count": 1,
  "total_cost": 4.5,
  "task_ids": ["task_xxx"],
  "tasks": [{ "id": "task_xxx", "status": "queued", "cost": 4.5 }]
}

第三方兼容接口

OpenAI 风格

POST /v1/videos

用于第三方画布、中转站和 OpenAI 风格视频客户端。支持 application/json，也支持 multipart/form-data 在创建任务时直接上传参考图片；兼容接口每次创建 1 个任务，成功返回 HTTP 200。

curl https://jinghong.asia/v1/videos \
  -X POST \
  -H "Authorization: Bearer sk_jh_xxx" \
  -F "model=sudashui-xg-sd2.5-900-720p" \
  -F "prompt=电影感镜头，人物缓慢回头" \
  -F "seconds=15" \
  -F "size=1280x720" \
  -F "input_reference=@person.png"

时长兼容 duration 或 seconds；比例兼容 aspect_ratio、ratio 或 size；提示词兼容 prompt、input 或 text；图片地址兼容 image、image_url、input_reference、reference_image、references 和 imageUrls。

兼容创建响应

{
  "id": "task_xxx",
  "object": "video",
  "status": "queued",
  "state": "queued",
  "internal_status": "queued",
  "progress": 0,
  "model": "sudashui-xg-sd2.5-900-720p",
  "cost": 4.5,
  "url": null,
  "video_url": null,
  "output": null,
  "error": null,
  "failure_reason": null
}

查询、预览与下载

标准任务：GET /v1/video/generations/:id

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

标准状态为 queued、running、completed、failed 或 canceled。完成后读取 video_url；失败时读取 failure_reason。

兼容任务：GET /v1/videos/:id

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

兼容状态为 queued、in_progress、completed、failed 或 cancelled。完成时 url、video_url 和 output.url 都返回结果地址；失败时 error.message 和 failure_reason 返回客户可读原因。

视频内容：GET 或 HEAD /v1/videos/:id/content

# 下载
curl -L https://jinghong.asia/v1/videos/task_xxx/content \
  -H "Authorization: Bearer sk_jh_xxx" \
  -o result.mp4

# 浏览器内预览
https://jinghong.asia/v1/videos/task_xxx/content?inline=1

必须使用创建该任务的账号所属 API Key。任务未完成时返回 409；接口支持上游允许的 Range 请求，适合视频播放器分段加载。

轮询建议

建议每 5–10 秒查询一次，直到任务进入 completed、failed 或 cancelled/canceled。客户端请求超时不代表上游任务失败，不要仅因单次轮询超时就在本地终止任务；应稍后使用同一个任务 ID 继续查询。

计费、退款与错误

计费规则

per_request 按“单价 × 生成数量”扣费；per_second 按“单价 × 时长 × 生成数量”扣费。创建任务时扣除积分；上游明确生成失败后，平台按任务原路退回本次积分。

错误响应格式

{
  "message": "具体错误原因",
  "error": {
    "message": "具体错误原因",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

上游返回中文错误时保留原意反馈；英文错误会转换为客户可读说明。API Key、上游密钥等敏感信息不会返回给客户。

常见 HTTP 状态码

400  参数、模型、时长、比例或参考素材不符合要求
401  API Key 无效或已撤销
402  账号积分不足
403  当前账号没有权限
404  接口或任务不存在，或任务不属于当前账号
409  视频任务尚未生成完成
413  上传文件超过 55 MB
500  惊鸿服务暂时异常
502  上游请求、素材上传或视频下载暂时异常