把想法，
变成可播放的画面。

KESTREL AI 把图片、视频、漫剧制作、无限画布与素材管理放进同一条创作流。输入一句话，从第一帧走到成片。

▶ 查看作品

05创作入口

∞画布空间

24/7本地就绪

LIVE GENERATION01 / 04

VIDEO STUDIO

让镜头先于语言发生。

↗

IMAGE GENERATION02

IMAGE / STYLE

一张图，打开一个世界。

CANVAS / ASSETS把灵感
放在一起。自由组织 · 随时回到创作现场

KESTREL AI API 文档更新日期：2026-10-12（v1.7） 1. 接入信息 Base URL：/api/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 /api/v1/models \ -H "Authorization: Bearer ysf_your_api_key_here" 模型目录只返回当前可用的视频模型和图片模型。请始终使用 /models 返回的 model id 发起请求。返回的 type 用于区分 video 与 image；视频模型的 supported_resolutions、supported_durations、max_*_references、billing_mode 与 customer_cost 是该模型的唯一有效参数和计费依据。当前主模型隐藏时不会出现在 /models、/capabilities 或画布模型发现接口中。主模型重新开放且出现在目录时，固定 30 秒，不传 duration；支持的分辨率、比例和参考素材数量以实时目录为准。次视频模型独立计费、独立执行，不会进入主模型链路；模型配置可能更新，接入方每次选择模型前应重新读取 /models。 MiniMax H3 特价模型（以 /models 返回的 model id 为准）固定输出 768p，支持 1–15 秒和 16:9 / 9:16。提交 H3 任务时请同时传入 resolution 与 aspect_ratio；服务端会按请求的画面比例提交给上游，不传入时使用该模型目录返回的默认值。参考素材数量以该模型的 max_*_references 为准。 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 /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 支持 Base64 Data URL 和 file_... ID。主模型还可使用 HTTPS 素材地址；次视频模型请使用 file_... ID 或画布上传生成的平台素材地址，避免第三方链接过期或不可访问。请只提交客户自身的参考素材；文件过期后需重新上传。 5. 提交视频任务 POST /video/generations 请求字段： model（必填，使用目录中 type=video 的模型） prompt（必填，视频提示词） resolution（可选，必须是该模型 supported_resolutions 之一） aspect_ratio（可选，必须是该模型 supported_aspect_ratios 之一） duration（次视频模型可选或必填，必须是该模型 supported_durations 之一） medias（可选，参考素材数组；数量上限以该模型 max_*_references 为准） Idempotency-Key（建议通过 HTTP Header 传入；每个业务请求使用唯一值）主模型重新开放且固定 30 秒时，无需传入 duration。次视频模型须按模型目录的 supported_durations 传入 duration；billing_mode=per_second 表示按秒计费，per_request 表示按次计费。请求示例： curl /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":"1080p","aspect_ratio":"16:9","duration":5,"medias":["file_example_id"]}' 提交成功响应示例： {"id":"task_example_id","object":"video.generation","status":"processing","model":"video_model_id","resolution":"720p","aspect_ratio":"16:9"} 提交成功返回平台任务 ID 和 processing。调用方只需按该任务 ID 轮询；同一业务请求必须复用同一个 Idempotency-Key。H3 等次视频模型可能先由服务端逐个导入参考素材，此时上游尚未返回任务编号，仍应查询平台任务 ID。平台会在后台调度模型请求、素材传输、供应商结果回调与状态轮询。调用方无需传入供应商地址、供应商 Key 或回调地址；这些内部参数不会出现在 API 响应中。若同一业务素材在有效期内重复使用，平台可在服务端复用已校验的素材副本，但不改变 file_... 的归属、有效期或访问权限。 6. 提交图片任务 POST /images/generations 请求字段： model（必填，使用目录中 type=image 的模型） prompt（必填，图片描述） size（可选，必须是模型返回的 sizes 之一） aspectRatio（可选，必须是模型返回的 supported_aspect_ratios 之一） referenceImages（可选，图片 Base64 Data URL 数组） mode（可选：text、character、storyboard、cinematicShot） curl /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 状态下不要重复提交。failed 时读取 error 字段；素材导入上游超时也会进入 failed，已冻结积分会自动退回，原任务不会自动重新提交。结果接口响应示例： {"id":"task_example_id","object":"video.result","urls":["https://result.example/video.mp4"]} 结果尚未准备好时返回 409 result_not_ready，请继续轮询状态接口。任务完成后使用 result 接口获取最终地址。 8. 并发与重试接口支持并发创建多个异步任务。请为每一个业务任务生成独立 Idempotency-Key；因网络超时、502 或连接中断重试同一个业务任务时，必须继续使用原 Key。请勿以短间隔重复创建相同任务，也不要在 processing 状态下重新提交。服务端会按模型和供应商进行队列调度，并对临时查询错误进行退避重试。处理时长取决于模型、素材大小和上游排队情况；调用方应以状态接口的 processing、succeeded、failed 为唯一任务判断依据。 9. 接入顺序模型读取 → 素材上传 → 任务提交 → 状态轮询 → 结果下载。接入方应保留任务 ID，并在网络重试时复用 Idempotency-Key。 10. 常见错误 401 invalid_api_key / auth_required：检查 Key 是否正确、已轮换或已停用 403 model_not_allowed：该 Key 未授权当前模型；重新读取 /models 后选择已授权模型 400 prompt_required / image_prompt_required：请提供提示词 400 model_not_available / video_model_not_available：模型当前未开放、已停用或供应商凭据不可用；请重新读取 /models 400 image_ratio_unavailable：当前图片模型不支持该比例，请读取模型目录 400 video_parameter_unavailable / video_duration_unavailable：当前视频模型不支持所选分辨率、比例或时长；请重新读取 /models 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 secondary_reference_requires_file_upload：次视频模型的参考素材必须先通过 /files 或画布上传接口上传 400 media_too_large：单个参考文件超过 20 MB 502 服务暂时无法处理：请保留原 Idempotency-Key，稍后使用原请求重试任务状态 failed：查看状态接口的 error 字段和退款记录；确认需要再次生成时，以新的业务请求和新的 Idempotency-Key 重新发起。不要重用已失败任务的任务 ID

把想法，
变成可播放的画面。

让镜头先于语言发生。

一张图，打开一个世界。

欢迎进入创作空间

视频制作

图片制作

视频超分

客户端 API

把想法，变成可播放的画面。

让镜头先于语言发生。

一张图，打开一个世界。

欢迎进入创作空间

图片制作

视频超分

客户端 API

把想法，
变成可播放的画面。