惊鸿开发者 API

登录惊鸿后点击顶部“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

# 第三方/OpenAI 视频兼容接口
POST /v1/videos
GET  /v1/videos/:id
GET  /v1/videos/:id/content

兼容第三方画布和 OpenAI 风格视频客户端，成功时返回 200 JSON。既可提交 application/json，也可使用 multipart/form-data 在同一请求中上传参考图片。

curl https://jinghong.asia/v1/videos \
  -X POST \
  -H "Authorization: Bearer sk_jh_xxx" \
  -F "model=d1-video" \
  -F "prompt=电影感镜头，人物缓慢回头" \
  -F "seconds=8" \
  -F "size=1080x1920" \
  -F "input_reference=@person.png"

时长兼容 duration 或 seconds；比例兼容 aspect_ratio、ratio 或 size；图片兼容 image、image_url、input_reference、reference_image、references 和 imageUrls。

轮询任务。status 为 queued、in_progress、completed、failed 或 cancelled。完成时 url、video_url 和 output.url 都会返回结果地址。

任务完成后直接流式读取或下载视频。必须使用创建该任务的惊鸿账号所属 API Key。

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

每个模型会返回清晰度、支持时长、画面比例、积分价格与素材数量限制。支持真人的模型还会返回 supports_real_people。部分模型还会返回提示词、参考素材时长和文件大小限制；提交任务前应以实时返回值为准。

{
  "id": "megaby-videos-standard-720p",
  "name": "MegaBy 卡脸 满血 · 720P（卡真人）",
  "resolution": "720p",
  "durations": ["4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"],
  "blocks_real_people": true,
  "aspect_ratios": ["9:16", "16:9", "1:1"],
  "max_runs": 1,
  "reference_limits": { "image": 9, "audio": 3, "video": 3, "total": 15 },
  "reference_duration_limits": { "audio": 15, "video": 15 },
  "reference_size_limits_bytes": { "imageFile": 20971520, "audioTotal": 52428800, "videoTotal": 209715200 },
  "max_prompt_characters": 1500,
  "points": 3,
  "billing_mode": "per_request"
}

D-1 为 720P 视频模型，支持 4～15 秒、最多 9 张参考图片，不接收音频或视频参考素材。可用比例为 9:16、16:9、1:1、4:3、3:4、21:9，提示词最多 5000 字符。

该模型按秒计费；实际每秒积分、当前可用时长和素材限制以 GET /v1/models 的实时返回值为准。平台会在多个 D-1 上游账号之间自动分配任务，调用方仍只使用自己的惊鸿 API Key 和惊鸿任务 ID，创建、查询和结果不会串到其他客户。

curl https://jinghong.asia/v1/video/generations \
  -X POST \
  -H "Authorization: Bearer sk_jh_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "d1-video",
    "prompt": "电影感镜头，人物缓慢回头",
    "duration": "8",
    "aspect_ratio": "9:16",
    "runs": 1,
    "imageUrls": ["https://example.com/person.png"]
  }'

使用 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",
  "bytes": 102400,
  "url": "https://...",
  "upstream_id": "file_xxx"
}

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", "size": 102400 },
      { "kind": "audio", "name": "旁白.mp3", "url": "https://example.com/voice.mp3", "size": 1048576, "durationSeconds": 8 }
    ]
  }'

references 支持 image、audio、video。每类数量及合计数量不能超过 reference_limits；模型返回 reference_duration_limits 时，音视频必须填写 durationSeconds；返回 reference_size_limits_bytes 时，应填写素材 size（字节，也兼容 bytes）。runs 不能超过 max_runs。超过限制时接口返回 400 且不会扣积分。runs 大于 1 时会创建多个独立任务。

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

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  服务或上游暂时异常