YunShuAi API 文档

更新日期：2026-09-16（v1.2）

1. 接入信息
Base URL：https://api.yunshuai.top/api/v1
鉴权：Authorization: Bearer ysf_your_api_key_here
响应格式：JSON

完整 API Key 只在创建或轮换时显示一次。请仅在服务端保存 Key，不要写入浏览器代码、网页源码、日志或公开仓库。每个 Key 的模型权限和钻石限额独立计算；限额不足时不会创建新任务。客户钻石是平台计费单位，与上游供应商积分分开管理，API 不返回上游账号、工作区或供应商信息。

2. 获取模型与能力
GET /models
GET /capabilities

请先读取模型目录，并使用返回的 id 作为请求中的 model。返回字段中的 type 用于区分 video 与 image；模型、分辨率、比例和图片能力均以接口返回为准。未在目录中返回的模型不会被外部视频接口接受。上游供应商、路由和账号信息不属于 API 响应的一部分。

curl https://api.yunshuai.top/api/v1/models \
  -H "Authorization: Bearer ysf_your_api_key_here"

3. 上传与管理参考素材
POST /files
GET /files/{file_id}
GET /files/{file_id}/content

POST /files 支持 multipart/form-data 或原始二进制上传。原始二进制上传时使用 X-Media-Filename 指定文件名。支持图片、视频、音频，单个文件最大 20 MB；单个音频参考文件时长不超过 30 秒。上传成功会返回 file_... ID 与 expires_at（默认保存约 2 小时）。file_... 仅可由创建它的同一 API Key 使用，并在 expires_at 后失效。

curl https://api.yunshuai.top/api/v1/files \
  -X POST \
  -H "Authorization: Bearer ysf_your_api_key_here" \
  -F "file=@reference.png"

响应示例：
{"id":"file_example_id","object":"file","filename":"reference.png","mime_type":"image/png","bytes":123456,"expires_at":1780000000}

视频请求中的 medias 使用 file_... ID；也支持 HTTPS 素材地址或 Base64 Data URL。请只提交当前业务自身的素材，素材地址不可用或已过期时请重新上传。

4. 视频模型
展示名称：seedance2.5 满血固定30s,30图10音频1视频
视频时长固定为 30 秒。
参考素材最多：图片 30 个、视频 1 个、音频 10 个。
支持分辨率：480p、720p、1080p。
支持比例以 /capabilities 返回值为准。

5. 提交视频任务
POST /video/generations

请求字段：
model（必填，使用 /models 返回的视频模型 id）
prompt（必填，视频提示词）
resolution（可选：480p、720p、1080p；默认 480p）
aspect_ratio（可选；支持值以 /capabilities 为准）
medias（可选；图片最多 30 个、视频最多 1 个、音频最多 10 个）
Idempotency-Key（建议通过 HTTP Header 传入；每个业务请求使用唯一值）

视频时长固定为 30 秒，无需提交 duration。请求受理后会冻结并按当前客户价格扣除钻石；上传、模型查询和预检本身不会扣除钻石。任务最终失败时平台自动退回本次任务钻石。同一 Idempotency-Key 在 30 分钟有效期内重复调用会返回第一次请求的任务，不会重复扣除钻石或重复创建任务；网络超时后请保留原 Key 重试。

curl https://api.yunshuai.top/api/v1/video/generations \
  -X POST \
  -H "Authorization: Bearer ysf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_example_0001" \
  -d '{"model":"video_model_id","prompt":"黄昏海边，镜头缓慢推进","resolution":"720p","aspect_ratio":"16:9","medias":["file_example_id"]}'

成功响应示例：
{"id":"task_example_id","object":"video.generation","status":"processing","model":"video_model_id","resolution":"720p","aspect_ratio":"16:9"}

6. 查询状态与获取结果
GET /video/generations/{id}
GET /video/generations/{id}/result

状态：processing（处理中）、succeeded（已完成）、failed（失败）、review（结果待人工核对）。每 10 至 15 秒使用同一个任务 ID 查询一次；处理中请勿重复提交同一业务请求。

结果接口响应示例：
{"id":"task_example_id","object":"video.result","urls":["https://result.example/video.mp4"]}

结果尚未准备好时返回 409 result_not_ready，请继续轮询状态接口。

7. 图片模型
图片模型与视频模型使用同一 API Key。先通过 /models 获取 type=image 的模型 id，再调用：
POST /images/generations

图片模型支持的尺寸、比例及参考图数量以 /models 和 /capabilities 返回值为准。请求字段为 model、prompt、size、aspectRatio；可选 referenceImages 使用图片 Base64 Data URL，最多 3 张。图片任务受理时冻结钻石，成功完成后扣除，失败自动退回。

curl https://api.yunshuai.top/api/v1/images/generations \
  -X POST \
  -H "Authorization: Bearer ysf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"image_model_id","prompt":"晨雾中的山谷","size":"1k","aspectRatio":"16:9"}'

成功响应会返回 jobId、url 与 imageUrl。图片生成失败时平台自动释放该次任务已冻结的钻石。

8. 常见错误
401 invalid_api_key：检查 API Key 是否正确或已停用
403 model_not_allowed：当前 Key 未开通该模型
400 prompt_required：请提供提示词
400 invalid_reference_media：检查素材类型、数量、格式或 HTTPS 地址
400 external_file_unavailable：file_... 已过期或不属于当前 API Key，请重新上传
400 media_too_large：单个参考文件超过 20 MB
429 api_diamond_limit_exceeded：已达到该 Key 的钻石限额
404 generation_not_found：任务不存在或不属于当前 Key
409 result_not_ready：结果尚未生成，请继续轮询
502 服务暂时无法处理：保留原 Idempotency-Key，稍后使用原请求重试