创建与查询
三种产品共用同一组创作任务接口。无论创建视频、图片还是应用，都可以使用相同的列表、详情和输出读取方式。
上传附件
三种产品都支持 input_file_ids。先上传文件：
curl -s "https://api.kpainter.ai/openapi/v1/files" \ -H "Authorization: Bearer $KPAINTER_API_KEY" \ -F "file=@./handbook.pdf"响应示例：
{ "file_id": "file_xxx", "name": "handbook.pdf", "mime_type": "application/pdf", "size_bytes": 248391}只在当前账号的创建请求中使用返回的 file_id。
创建
POST /creations公共字段：
| 字段 | 必填 | 说明 |
|---|---|---|
| type | 是 | video、image 或 app |
| prompt | 是 | 想要创建的内容 |
| instructions | 否 | 补充要求 |
| input_file_ids | 否 | 已上传的文件编号 |
| max_credits | 否 | 本次任务允许使用的积分上限 |
| video / image / app | 是 | 只发送与 type 对应的设置对象 |
示例：
{ "type": "app", "prompt": "根据培训手册做一个带即时反馈的安全知识测验", "input_file_ids": ["file_xxx"], "app": { "language": "zh" }}列表与详情
GET /creations?page=1&page_size=20GET /creations?type=video&page=1&page_size=20GET /creations/{id}详情中的常用字段：
| 字段 | 说明 |
|---|---|
| status | planning、producing、paused、ready 或 failed |
| progress_pct | 0–100 的单调进度 |
| estimated_remaining_seconds | 可靠时才返回的剩余时间 |
| estimated_credits | 当前任务的预估积分 |
| actual_credits | 成功后本次任务的实际积分 |
| has_usable_delivery | 是否已有可用结果 |
| available_actions | 当前允许执行的继续操作 |
| review | 解说视频可安全展示的大纲 |
| result_code | 可向用户解释的安全结果码 |
普通失败不会返回实际消费积分。没有可靠估算时，estimated_remaining_seconds 会省略。
获取输出
GET /creations/{id}/outputs仅展示接口返回的 outputs。不要猜测 URL，也不要使用未完成任务的中间文件。
稳定的客户端流程
- 读取 capabilities。
- 只提交一次参数有效的创建请求。
- 每隔数秒查询同一个 creation。
- ready 后读取 outputs。
- paused 时读取 available_actions，等待用户完成所需操作。
- failed 时展示安全原因，修改输入后再发起新请求。
- 网络状态不明时先查询现有 creation，不要直接重复创建。