视频任务、轮询与下载
视频任务有三个不同阶段：提交被受理、生成达到终态、结果成功下载。你的应用应分别记录它们。用户关闭页面、客户端超时或下载失败，都不能直接当作“没有生成”或“任务已取消”。
1. 创建与保存任务
POST /v1/videos 创建一个任务。请求头、model 和请求体见对应型号章节。正常受理返回 JSON 任务对象，主要字段如下。
| 字段 | 类型 | 含义 / 建议 |
|---|---|---|
| id | string | 本站任务 ID；一收到就持久化保存 |
| task_id | string，可选 | 旧客户端兼容字段；新接入优先 id |
| object | string | 通常为 video |
| model | string | 公开模型名 |
| status | string | 任务状态，不能只看 HTTP 200 |
| progress | integer | 通常 0–100；是进度提示，不是剩余时间 |
| created_at | integer | Unix 秒时间戳，不是毫秒 |
| completed_at | integer，可选 | 完成时间；未完成可能省略 |
| expires_at | integer，可选 | 若提供则表示相应过期提示，不能据此承诺永久可查 |
| seconds | string，可选 | 时长回显；不能据此认定实际容器时长 |
| size / resolution | string，可选 | 规格回显；以实际媒体为准 |
| usage | object，可选 | 型号相关的公开用量，可能只在完成后出现 |
| error | object，可选 | 失败说明；读取 message 与存在时的 code/type |
不要要求所有可选字段同时存在。兼容旧查询结果时可读取 data.id、data.task_id 等历史封装，但统一新接入应优先顶层 id。示例客户端会检查 ID 格式和查询响应身份。
建议自己的数据库记录：业务唯一 ID、本站入口、model、Key 的内部引用、分组、参数摘要、提交时间、task_id、最近状态、最后查询时间、下载路径和账单核对状态。不要把完整 Key 存进任务日志或分享给前端。
2. 查询状态
GET /v1/videos/{task_id}，携带原 API Key。
curl --fail-with-body --max-time 30 \
"https://openpix.cc/v1/videos/$MXB_VIDEO_TASK_ID" \
-H "Authorization: Bearer $MXB_API_KEY"
| 统一状态 | 含义 | 应做什么 |
|---|---|---|
| queued | 已受理、等待执行 | 保留 ID，间隔查询 |
| in_progress | 处理中 | 继续查询，不再创建相同任务 |
| completed | 任务报告成功 | 开始下载、校验视频文件 |
| failed | 任务报告失败 | 停止正常轮询，读错误并核对账单 |
| unknown 或未识别值 | 暂无法按已有状态处理 | 保存原响应摘要，有界续查或人工核对，不能当成功 |
兼容旧任务时，可能遇到 pending、submitted、processing、running、success、succeeded、done、failure、error、cancelled、canceled、expired 等值。客户端可以将已知成功/失败别名归一，但不要对任意未知字符串做成功判断。
普通成功结果结构示意：
{
"id": "task_example_video_001",
"object": "video",
"model": "dreamina-seedance-2-0-mini-260615",
"status": "completed",
"progress": 100,
"seconds": "5",
"usage": {"completion_tokens": 40594, "total_tokens": 40594}
}
数值与 ID 为示意；不是任意 5 秒视频的固定用量。按秒/按次视频可能没有这一套 usage。
3. 轮询频率与截止时间
建议初始每 5 秒查询一次，多个任务加入随机抖动。将三种超时分别配置：
| 超时 | 示例设置 | 到期后含义 |
|---|---|---|
| 单次创建连接 | 120 秒 | 提交结果可能未知，不能自动重发 |
| 单次 GET 查询 | 30 秒 | 仅这一次查询失败，继续使用原 ID |
| 总等待时间 | 30 分钟 | 客户端暂停等待，可稍后继续查询 |
这些是示例配置，不是生成时延保证或服务 SLA。任务可能较慢，不能因 progress 停在某个数字或多次不变就重发 POST。
429 或临时 5xx 可对 GET 做有界退避。服务器提供 Retry-After 时尊重其值；未提供时逐步增加间隔并设置上限。401/403 应先修复凭据或权限，400 参数错误不能原样重试。
4. 下载主视频
GET /v1/videos/{task_id}/content 返回视频二进制。此入口需要本站 API Key；不要直接把它当作浏览器 video 标签的免鉴权 URL。
curl --fail --max-time 180 \
"https://openpix.cc/v1/videos/$MXB_VIDEO_TASK_ID/content" \
-H "Authorization: Bearer $MXB_API_KEY" \
--output result.mp4
下载到临时文件（如 .part），校验成功后再替换正式文件。至少检查：
- HTTP 为预期的 200，或断点请求的 206。
- 响应确为视频，而不是被保存成 .mp4 的 JSON/HTML 错误页。
- 文件非空，大小合理，能被实际播放器或媒体工具解码。
- 业务要求精确尺寸、时长、帧率时，读取真实媒体信息，而不是只看请求参数。
结果链接可能临时有效。完成后及时保存到自己的存储，不要承诺本站永久托管。
5. HEAD 与 Range
完成后可读取响应头：
curl --head --fail --max-time 30 \
"https://openpix.cc/v1/videos/$MXB_VIDEO_TASK_ID/content" \
-H "Authorization: Bearer $MXB_API_KEY"
读取开头一段数据：
curl --fail --max-time 60 \
"https://openpix.cc/v1/videos/$MXB_VIDEO_TASK_ID/content" \
-H "Authorization: Bearer $MXB_API_KEY" \
-H 'Range: bytes=0-1048575' \
--output first-part.bin
支持部分内容时返回 206 与 Content-Range。若返回 200，应按完整文件处理，不能直接追加到已有断点文件后面。416 表示范围不适用，重新检查当前资源长度。一次只发送一个连续字节范围；本手册不承诺多段 Range。
HEAD 不能代替任务状态查询。结果尚未准备好时下载接口可能返回 400；不存在或不可访问任务可能 404，资源失效可能 410，临时下载问题可能 5xx。都先查询原任务，不应立即创建新视频。
6. 可用制品与末帧
某些型号可附带末帧。完成后查询：
curl --fail-with-body --max-time 30 \
"https://openpix.cc/v1/tasks/$MXB_VIDEO_TASK_ID/artifacts" \
-H "Authorization: Bearer $MXB_API_KEY"
只使用实际返回列表中的制品。Mini/Fast 请求 return_last_frame=true 且任务实际返回末帧时，才会存在 last_frame。其他型号不应假设有封面、字幕或缩略图。
制品内容通用入口为 GET /v1/tasks/{task_id}/artifacts/{artifact_key}/content。artifact_key 使用实际列表值，不自行猜测。带本站访问签名的返回链接应作为有访问能力的临时链接保护，不公开日志或长期缓存。
对于任何响应里的 URL：先校验 HTTPS 与预期来源，再决定访问方式。本站 Key 只发送到固定本站 API origin；访问外部媒体 URL 不携带本站 Key。示例客户端直接使用本站内容入口，并拒绝自动跨地址重定向。
7. 结果未知、失败与重新提交
| 情况 | 如何恢复 |
|---|---|
| POST 成功，已有 ID | 始终查询原 ID |
| POST 断线/超时，没拿到 ID | 标记“提交结果未知”；查看控制台任务与调用记录，避免自动重提 |
| GET 查询临时失败 | 保存 ID，稍后重试同一次查询 |
| 客户端总等待到期 | 停止本次等待，保留 ID，之后续查 |
| status=failed | 读错误、核对账单；修正原因后再决定创建新任务 |
| completed，但下载失败 | 重试原 content 入口；不要重新生成 |
| 已下载但文件损坏 | 校验下载响应和文件完整性，重新下载原任务 |
目前没有跨所有视频型号统一可依赖的客户端 Idempotency-Key 去重承诺；同样的提示词也不构成自动去重。示例程序在发送 POST 前先记录“提交结果未知”，避免进程中断后无意重复收费。
没有公开统一的 DELETE 取消任务能力。停止轮询、关闭页面、撤销请求或删除自己保存的状态文件，不等于服务端停止生成。
8. 错误与排查顺序
| 情况 | 检查重点 |
|---|---|
| 401 | Bearer 格式、Key 是否有效/过期/撤销 |
| 403 或权限提示 | Key 分组、模型限制、账户权限 |
| model_not_found / 无可用模型 | 完整型号、当前模型目录、型号参数、实时可用性 |
| 参数错误 | 所选型号的时长、分辨率、参考素材字段及互斥规则 |
| 素材失败 | URL 是否真正返回媒体、是否需要 Cookie、是否过期、格式是否兼容 |
| 额度不足 | 账户余额、Key 额度及提交时所需的预留额度 |
| 404 查询任务 | ID、入口、账户/原 Key、任务是否仍在可访问范围 |
| 200 且 failed | 任务层失败，不能当 HTTP 调用成功就忽略 |
| 429 / 临时 5xx | GET 退避；POST 先确定是否已经受理 |
定位时提供：公开 model、分组名称、本站任务 ID、请求时间与时区、HTTP 状态、本站 request_id（如有）、错误摘要与已脱敏参数。不要提供完整 Key、Cookie、私有素材签名或整段 Authorization。
9. 账单核对
按次、按秒、视频 Token 是三种独立计费方式。提交预留、完成补扣或退款可能分成多条记录，应关联同一个任务合计核对。任务进度字段、HTTP 状态、客户端的超时异常，都不是独立的收退款凭证。
更换 Key 分组会影响新提交任务的权限与报价，不能靠在查询 JSON 中加 group 改变已受理任务费用。具体规则见分组与计费。