API 文档
点击下方按钮复制完整文档
YunShuAi API 文档
更新日期：2026-09-16（v1.1）
1. 接入信息
标准 Base URL：https://api.yunshuai.top/api/v1
兼容 Base URL：https://api.yunshuai.top/v1
鉴权：Authorization: Bearer ysf_your_api_key_here
响应格式：JSON
这是统一的聚合接口。模型目录会返回当前已启用的视频和图片模型，具体能力、尺寸、比例以接口返回为准。完整 API Key 仅在创建或轮换时显示一次，请保存在服务端密钥管理中，不要写入浏览器代码、网页源码、日志或公开仓库。
2. 鉴权与计费
所有请求均须携带：
Authorization: Bearer ysf_your_api_key_here
每个 API Key 可设置独立限额，0 表示不限额。余额不足、Key 未启用、超过限额或模型未授权时，任务不会创建。失败任务按平台规则结算。
3. 获取模型与能力
GET /models
GET /capabilities
curl https://api.yunshuai.top/api/v1/models \
-H "Authorization: Bearer ysf_your_api_key_here"
视频模型展示名称：seedance2.5 满血固定30s,30图10音频1视频。
请始终使用 /models 返回的 model id 发起请求。返回的 type 用于区分 video 与 image；图片模型的尺寸、比例与参考图能力同样以模型目录和 /capabilities 返回值为准。
4. 上传参考素材
POST /files
Content-Type：multipart/form-data 或原始二进制
GET /files/{file_id}
GET /files/{file_id}/content
支持图片、视频、音频。单个文件最大 20 MB；单个音频参考文件时长不超过 30 秒。上传成功会返回 file_... ID 与 expires_at。文件仅属于创建它的 API Key，默认在 2 小时后过期。原始二进制上传时请通过 X-Media-Filename 指定文件名。
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 支持 HTTPS 素材地址、Base64 Data URL 和 file_... ID。请只提交客户自身的参考素材；文件过期后需重新上传。
5. 提交视频任务
POST /video/generations
请求字段：
model（必填，使用目录中 type=video 的模型）
prompt（必填，视频提示词）
resolution（可选：480p、720p、1080p；默认 480p）
aspect_ratio（可选，默认 16:9）
medias（可选，参考素材数组；图片最多 30 个、视频最多 1 个、音频最多 10 个）
Idempotency-Key（建议通过 HTTP Header 传入；每个业务请求使用唯一值）
视频时长固定为 30 秒；支持比例以 /capabilities 返回值为准，无需传入 duration。
请求示例：
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-20260914-001" \
-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"}
提交成功返回 processing。调用方只需按任务 ID 轮询；同一业务请求必须复用同一个 Idempotency-Key。
6. 提交图片任务
POST /images/generations
请求字段：
model（必填，使用目录中 type=image 的模型）
prompt（必填，图片描述）
size（可选，必须是模型返回的 sizes 之一）
aspectRatio（可选，必须是模型返回的 supported_aspect_ratios 之一）
referenceImages（可选，图片 Base64 Data URL 数组）
mode（可选：text、character、storyboard、cinematicShot）
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":"gpt-image-2 2K","prompt":"电影级室内肖像","size":"2048x2048","aspectRatio":"1:1"}'
成功响应包含 jobId、imageUrl 和 credits。图片任务失败会自动退回本次扣除的💎。
7. 查询视频状态与获取结果
GET /video/generations/{id}
GET /video/generations/{id}/result
状态：processing（处理中）、succeeded（已完成）、failed（生成失败）。请使用同一个任务 ID 每 10 至 15 秒查询一次；processing 状态下不要重复提交。
结果接口响应示例：
{"id":"task_example_id","object":"video.result","urls":["https://result.example/video.mp4"]}
结果尚未准备好时返回 409 result_not_ready，请继续轮询状态接口。任务完成后使用 result 接口获取最终地址。
8. 接入顺序
模型读取 → 素材上传 → 任务提交 → 状态轮询 → 结果下载。
接入方应保留任务 ID，并在网络重试时复用 Idempotency-Key。
9. 常见错误
401 invalid_api_key / auth_required：检查 Key 是否正确、已轮换或已停用
403 model_not_allowed：该 Key 未授权当前模型；重新读取 /models 后选择已授权模型
400 prompt_required / image_prompt_required：请提供提示词
400 image_ratio_unavailable：当前图片模型不支持该比例，请读取模型目录
400 customer_credit_insufficient：余额不足，请充值后重新提交
429 api_diamond_limit_exceeded：已达到该 Key 的💎限额
404 generation_not_found：任务不存在或不属于当前 Key
409 result_not_ready：结果尚未生成，请继续轮询
400 invalid_reference_media / external_file_unavailable：参考素材格式无效、文件已过期或不属于当前 API Key；请重新上传后使用新的 file_... ID
400 media_too_large：单个参考文件超过 20 MB
502 服务暂时无法处理：请保留原 Idempotency-Key，稍后使用原请求重试
任务状态 failed：查看状态接口的 error 字段；使用新的业务请求和新的 Idempotency-Key 重新发起
