图片与视频生成 API 文档
完整接口说明与全部模型目录
协议对接
下游服务可直接通过 HTTPS 调用 XPQMM API。使用你自己的 API Key;模型 ID 和面向客户的价格以实时模型目录为准。
GET
https://xpqmm.lol/api/modelsPOST
https://xpqmm.lol/api/mediaPOST
https://xpqmm.lol/api/media/validatePOST
https://xpqmm.lol/api/videosGET
https://xpqmm.lol/api/videos/{task_id}GET
https://xpqmm.lol/api/videos/{task_id}/download-ticketPOST
https://xpqmm.lol/api/images视频必须轮询:
POST /api/videos 的 201 只表示创建成功。保存完整的 body.task.id,每 5–10 秒调用 GET /api/videos/{task_id};状态读取 body.task.status,不是 body.status。任务 ID 拼接 URL 时必须编码。完整输入校验:每个图片、视频、音频节点分别上传,全部 ID 先调用
/api/media/validate。提交时携带 text_nodes、reference_manifest 和期望数量;创建响应必须核对 task.input_receipt,数量或提示词摘要不一致时不要继续。URL
https://xpqmm.lol/v1GET
https://xpqmm.lol/v1/modelsPOST
https://xpqmm.lol/api/mediaPOST
https://xpqmm.lol/v1/images/generationsPOST
https://xpqmm.lol/v1/videosGET
https://xpqmm.lol/v1/videos/{video_id}GET
https://xpqmm.lol/v1/videos/{video_id}/content?download=1POST
https://xpqmm.lol/v1/chat/completions下游配置时 Base URL 必须填写
https://xpqmm.lol/v1,再填写 API Key;下游即可从 GET /models 自动读取当前已上架的全部图片和视频模型。OpenAI 兼容视频响应是扁平对象:创建后保存 body.id,核对 body.input_receipt,轮询 GET /videos/{video_id} 并读取 body.status。全部参考素材必须先逐个上传到 POST https://xpqmm.lol/api/media,再把所有 media.id 放入 references 或 input_reference。账户余额与用量查询
下游可实时读取余额、累计花费、退款和生成中预占金额;使用同一 API Key 服务端查询。
GET
https://xpqmm.lol/api/account/usage实时已上架模型
页面每次打开都会从服务端读取,只显示当前已上架的图片和视频模型。下游提交时使用卡片中的公开模型 ID,不需要上游通道前缀。
正在读取当前模型目录…
# 图片与视频生成 API 文档
本文档适用于站点 https://xpqmm.lol,覆盖素材上传、图片生成、视频生成、状态查询、视频预览和下载。
## 1. 基础信息
- Base URL:https://xpqmm.lol
- 请求与响应:application/json,素材上传除外
- 鉴权:Authorization: Bearer sk-xpqmm-...
- 也支持:X-API-Key: sk-xpqmm-...
- 公开实时目录:GET /api/catalog/models(无需鉴权,仅用于文档展示和通用参数发现)
- 客户实时目录:GET /api/models(平台协议)或 GET /v1/models(OpenAI 兼容)
- 任务及媒体默认保留 24 小时,请及时下载结果
- 后端每 10 秒检查一次上游任务,并在成功后异步拉取视频到本站
请求中的 model 必须使用模型 id。页面展示应使用模型接口返回的 name;管理员修改名称后,前后端会通过该字段同步显示。
## 协议对接入口
下游应用可直接通过 HTTPS 调用本站 API。图片和视频均提供 OpenAI 风格兼容入口;兼容入口仍使用本站模型 ID、客户价格和任务缓存规则。
### 平台统一协议(图片与视频)
- Base URL:`https://xpqmm.lol`
- 鉴权:`Authorization: Bearer YOUR_API_KEY`
- 模型目录:`GET /api/models`
- 上传素材:`POST /api/media`
- 校验全部素材:`POST /api/media/validate`
- 提交视频:`POST /api/videos`
- 查询视频任务:`GET /api/videos/{task_id}`
- 获取下载票据:`GET /api/videos/{task_id}/download-ticket`
- 下载视频:`GET /api/videos/{task_id}/content?download=1`
- 提交图片:`POST /api/images`
- 查询账户余额与用量:`GET /api/account/usage`
视频提交是异步操作:`POST /api/videos` 返回 HTTP 201 仅表示任务创建成功,并不表示视频已经生成完成。下游必须保存响应中的完整 `body.task.id`,随后轮询 `GET /api/videos/{task_id}`。平台协议的状态字段位于 `body.task.status`,不是 `body.status`;任务 ID 可能包含 `::`,拼接 URL 时必须使用 `encodeURIComponent`、`urllib.parse.quote(..., safe='')` 或等价编码。API Key 仅用于服务端请求,不要放在公开网页中。
`GET /api/account/usage` 返回当前 API Key 所属账户的 `balance`、`total_spent`、`total_charged`、`total_refunded` 和 `pending`。建议下游每 5 秒同步一次,并以 `*_micros` 整数金额做精确计算;完整响应字段和示例见“实时同步账户余额与累计花费”。
#### 下游完整输入协议(不得漏素材或文字节点)
接入方必须按以下顺序实现完整链路,不能把本地路径、素材 URL 或节点对象直接塞进 `references`:
1. 每次生成前调用 `GET /api/models` 或 `GET /v1/models`,取得当前已上架模型及 `max_image_refs`、`max_video_refs`、`max_audio_refs`、时长、比例和分辨率限制。
2. 遍历当前任务的全部素材节点。每一张图片、每一段参考视频、每一个音频文件都分别调用一次 `POST /api/media`,保存响应中的 `media.id`、`media.kind` 和原节点标识。
3. 调用 `POST /api/media/validate`,一次提交全部 `media.id`。只有 `invalid_ids` 为空并且 `valid_ids` 数量与素材节点数量一致时,才允许创建任务。
4. 按原节点顺序把全部 `media.id` 放入 `references`;同时提交同顺序的 `reference_manifest`,记录 `media_id`、`kind`、`label` 和 `node_id`。
5. 主提示词放入 `prompt`。其他文字节点放入 `text_nodes`,每项使用 `{node_id, label, text}`;服务端会按顺序无损合并为最终提示词。
6. 建议同时传 `expected_reference_count`、`expected_text_node_count`、`expected_prompt_chars` 和 `expected_prompt_sha256`。任何数量或摘要不一致都会返回 400 并停止生成,避免静默漏字段和误扣费。
7. 创建成功后核对响应中的 `task.input_receipt`(OpenAI 兼容协议为顶层 `input_receipt`)。只有素材数量、分类、ID、文字节点数量和提示词 SHA-256 与本地一致,才把任务标记为已完整受理。
8. 保存完整任务 ID,轮询到成功且 `video_available=true` 后下载视频。不要把 HTTP 201 或 `queued` 当成生成完成。
严格请求示例:
~~~json
{
"client_submission_id": "customer-job-20261120-0001",
"model": "从实时模型目录取得的视频模型 ID",
"prompt": "主提示词:保持人物、服装和场景连续。",
"text_nodes": [
{"node_id": "text-001", "label": "镜头一", "text": "女主从门口走向窗边,镜头缓慢推进。"},
{"node_id": "text-002", "label": "镜头二", "text": "她回头看向镜头,环境光保持一致。"}
],
"references": ["media_image_id", "media_video_id", "media_audio_id"],
"reference_manifest": [
{"media_id": "media_image_id", "kind": "image", "label": "女主角色图", "node_id": "asset-001"},
{"media_id": "media_video_id", "kind": "video", "label": "动作参考", "node_id": "asset-002"},
{"media_id": "media_audio_id", "kind": "audio", "label": "对白参考", "node_id": "asset-003"}
],
"expected_reference_count": 3,
"expected_text_node_count": 2,
"expected_prompt_chars": 67,
"expected_prompt_sha256": "f1e6783dae359c8d9aababfeaf52c0c958f9cc0d7394d4e38013a9440343e5f0",
"seconds": 10,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
~~~
`reference_manifest` 与 `references` 必须数量一致、顺序一致,`kind` 必须与实际上传文件类型一致。服务端返回的 `input_receipt.reference_ids` 保持请求顺序,`reference_kinds` 分别统计图片、视频和音频,`prompt_sha256` 是服务端最终发送给生成通道的提示词摘要。旧客户仍可只传 `prompt + references`,新接入和插件接入应使用以上严格字段。
```bash
curl -X POST 'https://xpqmm.lol/api/videos' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"model":"MODEL_ID","prompt":"镜头缓慢推进","seconds":10,"resolution":"720p","aspect_ratio":"16:9","references":[]}'
curl 'https://xpqmm.lol/api/videos/TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
### OpenAI 兼容协议(图片、视频与聊天)
- Base URL:`https://xpqmm.lol/v1`
- 实时模型目录:`https://xpqmm.lol/v1/models`
- 鉴权:`Authorization: Bearer YOUR_API_KEY`
- 图片生成:`POST /v1/images/generations`
- 视频生成:`POST /v1/videos`
- 查询视频:`GET /v1/videos/{video_id}`
- 视频内容:`GET /v1/videos/{video_id}/content`
- 聊天补全:`POST /v1/chat/completions`
- 模型列表:`GET /v1/models`(仅返回当前可用的图片和视频模型)
- 余额与用量查询使用本站平台统一接口:`GET /api/account/usage`。
在下游软件中只需填写 Base URL `https://xpqmm.lol/v1` 和 API Key。标准 OpenAI 客户端会相对 Base URL 请求 `GET /models`,实际访问本站实时接口 `GET /v1/models`。不要把 Base URL 填成不带 `/v1` 的站点根地址,否则下游请求的不是协议模型目录。
兼容视频请求会把 `size`(例如 `1280x720`)转换为本站模型支持的分辨率和比例;也支持 `seconds`、`prompt`、`text_nodes`、`model`、`references`、`reference_manifest`、完整性校验字段和 `input_reference`。`references` / `input_reference` 必须填写本站 `POST /api/media` 返回的 `media.id`,不能填写本地路径,也不要直接填写外站 URL。创建成功后返回扁平的 OpenAI 风格视频任务对象,状态直接读取 `body.status`;输入验收结果读取 `body.input_receipt`。保存完整的 `body.id`,使用 `GET /v1/videos/{video_id}` 轮询。状态为 `completed` 且 `video_available` 为真后读取 `url` 或访问 `/content`。图片兼容入口返回标准 `data[].url`。不要混用平台协议的嵌套响应和 OpenAI 兼容协议的扁平响应。
图片请求示例:
~~~bash
curl -X POST 'https://xpqmm.lol/v1/images/generations' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{"model":"IMAGE_MODEL_ID","prompt":"一只猫坐在窗边","size":"1024x1024","n":1}'
~~~
视频请求和轮询示例:
~~~bash
curl -X POST 'https://xpqmm.lol/v1/videos' \\
-H 'Authorization: Bearer YOUR_API_KEY' \\
-H 'Content-Type: application/json' \\
-d '{"model":"VIDEO_MODEL_ID","prompt":"镜头缓慢推进","seconds":5,"size":"1280x720"}'
curl 'https://xpqmm.lol/v1/videos/VIDEO_ID' \\
-H 'Authorization: Bearer YOUR_API_KEY'
~~~
视频任务状态:`queued`、`in_progress`、`completed`、`failed`。只有 `completed` 且 `video_available` 为真时才读取视频内容;如果仍在本站缓存,继续轮询,不要判定生成失败。
## 2. 通用响应与错误码
成功响应通常包含 success: true。失败响应通常包含 error 或 message。
| HTTP | 含义 | 建议处理 |
|---:|---|---|
| 400 | 参数错误 | 检查模型、时长、分辨率、比例和素材数量 |
| 401 | API Key 无效或未登录 | 更换有效 API Key |
| 402 | 余额不足 | 充值后重试 |
| 403 | 来源校验失败 | Cookie 写请求需来自允许的站点来源 |
| 404 | 任务或资源不存在 | 检查任务 ID,或资源已被清理 |
| 409 | 模型不可用或幂等冲突 | 刷新模型目录;幂等 ID 不要复用于不同参数 |
| 410 | 资源已过期 | 重新生成;结果需在 24 小时内下载 |
| 429 | 请求过快 | 按 Retry-After 等待后重试 |
| 502 | 上游异常或源文件未完整就绪 | 保持任务记录并稍后重试 |
| 503 | 通道不可用或容量不足 | 换模型或稍后重试 |
## 3. 获取模型目录
### GET /api/models
返回当前前台可用模型及管理员设置的显示名称。调用前应先刷新此接口,不要把显示名称当作 model 参数。
~~~bash
curl -sS https://xpqmm.lol/api/models -H 'Authorization: Bearer sk-xpqmm-REPLACE_ME'
~~~
主要字段:
| 字段 | 说明 |
|---|---|
| id | 请求时使用的公开模型 ID,不包含内部上游通道前缀 |
| name | 前台显示名称,可由后台管理员修改 |
| type | image 或 video |
| duration | 支持的视频时长范围或档位 |
| resolution / resolutions | 原始分辨率规则 / 已上架且可提交的分辨率数组 |
| aspect_ratio / aspect_ratios | 原始画面比例规则 / 可提交的画面比例数组 |
| duration / duration_rule | 原始视频时长规则 / 规范化的 range 或 enum 规则 |
| max_image_refs | 最多图片参考数 |
| max_video_refs | 最多视频参考数 |
| max_audio_refs | 最多音频参考数 |
| max_total_refs | 单次请求最多参考素材总数 |
| prompt_max_chars | 上游明确给出的提示词字符上限;未返回时不要自行假定 |
| reference_input | 当前固定为 media_id |
| reference_upload_endpoint | 当前固定为 /api/media |
| price / price_unit | 当前售价与计费单位 |
| resolution_prices | 按分辨率计价时的价格表 |
| resolution_variants | 视频按“分辨率 + 是否含参考视频”的上架状态和价格 |
| pricing_options | 仅包含当前实际可提交规格的规范化价格选项 |
| enabled | 是否启用 |
本目录旁的 `models.json` 已映射到实时接口 `/api/catalog/models`,刷新文件或在线文档时会重新读取当前已上架的图片/视频模型,不需要人工重新生成静态清单。公开目录使用平台通用价格;当前 API Key 的客户分组价格和最终可调用权限始终以带 API Key 调用 `GET /api/models` 或 `GET /v1/models` 为准。
管理员在后台上架、下架或改名后:
1. 模型广场在手动刷新、窗口重新聚焦或最长 60 秒的定时刷新后自动同步。
2. 在线 API 文档在页面刷新或点击“刷新实时目录”后自动同步。
3. `/api-docs/models.json` 与 `/api/catalog/models` 会动态返回最新已上架目录。
4. 图片生成、视频生成、素材上传、任务查询和视频下载继续使用原接口,不受展示层隐藏渠道名称影响。
视频价格必须优先读取 `pricing_options` 或 `resolution_variants`:同一模型的 480p / 720p、无视频参考 / 含视频参考可能价格不同。不要只读取顶层 `price` 后套用到所有规格。
## 4. 实时同步账户余额与累计花费
### GET /api/account/usage
使用 API Key 查询当前 Key 所属账户的余额与消费汇总。建议每 5 秒轮询一次;接口返回 `Cache-Control: no-store`,每次响应都是服务端最新快照。累计花费依据本站实际扣积分记录计算,不是上游成本或模型目录标价。
~~~bash
curl -sS https://xpqmm.lol/api/account/usage -H 'Authorization: Bearer sk-xpqmm-REPLACE_ME'
~~~
响应示例:
~~~json
{
"success": true,
"data": {
"balance": 120.5,
"balance_micros": 120500000,
"total_charged": 28.75,
"total_charged_micros": 28750000,
"total_refunded": 1.25,
"total_refunded_micros": 1250000,
"total_spent": 27.5,
"total_spent_micros": 27500000,
"pending": 0.6,
"pending_micros": 600000,
"observed_at_ms": 1794400000000
}
}
~~~
| 字段 | 说明 |
|---|---|
| balance | 当前账户余额,积分 |
| total_charged | 已完成结算的累计扣费总额,积分 |
| total_refunded | 已退款总额,积分 |
| total_spent | 净累计花费,等于累计扣费减去退款,不低于 0 |
| pending | 生成中已预占、尚未最终结算的积分 |
| *_micros | 对应金额的整数微积分(1 积分 = 1,000,000 微积分),适合精确比较 |
| observed_at_ms | 服务端生成快照的 Unix 毫秒时间戳 |
可持续同步的 Node.js 示例(将密钥放在环境变量 `XPQMM_API_KEY` 中):
~~~javascript
const base = 'https://xpqmm.lol';
const key = process.env.XPQMM_API_KEY;
if (!key) throw new Error('请设置 XPQMM_API_KEY');
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
while (true) {
try {
const response = await fetch(`${base}/api/account/usage`, {
headers: {Authorization: `Bearer ${key}`},
cache: 'no-store',
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.message || `HTTP ${response.status}`);
console.log(JSON.stringify({
balance: result.data.balance,
total_spent: result.data.total_spent,
pending: result.data.pending,
observed_at_ms: result.data.observed_at_ms,
}));
} catch (error) {
console.error('账户同步失败:', error.message);
}
await sleep(5000);
}
~~~
## 5. 上传素材
### POST /api/media
Content-Type 必须为 multipart/form-data,文件字段名为 file。单个源文件最大 256 MB,支持常见图片、视频和音频格式。
~~~bash
curl -sS https://xpqmm.lol/api/media -H 'Authorization: Bearer sk-xpqmm-REPLACE_ME' -F 'file=@C:/path/reference.png'
~~~
成功时返回 201:
~~~json
{
"success": true,
"media": {
"id": "media_xxx",
"kind": "image",
"name": "reference.png",
"url": "https://xpqmm.lol/uploads/reference/...",
"size": 123456,
"original_size": 123456,
"compressed": false
}
}
~~~
后续生成请求的 `references` 填写 `media.id`,不要直接填写本地文件路径或 `media.url`。OpenAI 兼容视频入口的 `input_reference` 也使用同一组 `media.id`;单个 ID 可传字符串,多个 ID 传数组。
### POST /api/media/validate
提交前可检查素材 ID 是否仍有效。
~~~json
{"ids":["media_xxx","media_yyy"]}
~~~
响应包含 `valid_ids` 和 `invalid_ids`。接入方必须比较 `valid_ids.length` 与本次素材节点总数;只检查 HTTP 200 而不检查数组数量,仍可能漏传素材。
## 6. 图片生成
### POST /api/images
兼容入口:POST /v1/images/generations。图片接口为同步返回,成功响应直接包含 result_url。
~~~json
{
"model": "从 /api/models 取得的图片模型 id",
"prompt": "保持人物一致,生成电影感雨夜街景",
"references": ["media_xxx"],
"resolution": "1K",
"aspect_ratio": "16:9"
}
~~~
可选参数还包括 size、quality、background。prompt 长度为 1 至 10000 字符,素材数量不得超过对应模型的限制。
~~~bash
curl -sS https://xpqmm.lol/api/images -H 'Authorization: Bearer sk-xpqmm-REPLACE_ME' -H 'Content-Type: application/json' --data '{"model":"MODEL_ID","prompt":"一只猫坐在窗边","references":[],"resolution":"1K","aspect_ratio":"1:1"}'
~~~
成功时返回 201,重点字段为 task.id、task.status、task.result_url、task.charged 和 balance。
## 7. 视频生成
### POST /api/videos
~~~json
{
"client_submission_id": "client-20261108-0001",
"model": "从 /api/models 取得的视频模型 id",
"prompt": "保持人物和场景连续",
"text_nodes": [
{"node_id":"text-001","label":"镜头一","text":"女孩抬头看向镜头,镜头缓慢推进"}
],
"references": ["media_image_xxx", "media_audio_xxx"],
"reference_manifest": [
{"media_id":"media_image_xxx","kind":"image","label":"女主角色图","node_id":"asset-001"},
{"media_id":"media_audio_xxx","kind":"audio","label":"对白参考","node_id":"asset-002"}
],
"expected_reference_count": 2,
"expected_text_node_count": 1,
"seconds": 15,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true,
"watermark": false
}
~~~
`client_submission_id` 建议每次提交都生成一个唯一值,用于网络超时后的幂等恢复。同一个值不得用于不同参数。`model` 必须使用实时目录返回的公开 ID,不要自行拼接 `gg::` 等内部上游通道前缀。旧版完整 ID 继续兼容,但新接入应使用公开 ID。`seconds`、`resolution`、`aspect_ratio`、参考素材数量以及音频和水印能力必须符合所选模型目录。
完整性字段:
| 字段 | 作用 |
|---|---|
| text_nodes / prompt_nodes | 额外文字节点数组;支持字符串,或 `{node_id,label,text}` 对象 |
| reference_manifest | 与 references 同长度、同顺序的素材节点清单 |
| expected_reference_count | 客户端预期素材节点数,不一致时停止提交 |
| expected_text_node_count | 客户端预期文字节点数,不一致时停止提交 |
| expected_prompt_chars | 最终合并提示词字符数,不一致时停止提交 |
| expected_prompt_sha256 | 最终合并提示词的 64 位小写 SHA-256,不一致时停止提交 |
最终提示词合并规则固定为:非空 `prompt` 在前,每个文字节点按原数组顺序追加;有 `label` 或 `node_id` 时使用 `[标签]\n文字内容`,各部分之间使用两个换行符。客户端据此计算 `expected_prompt_chars` 和 `expected_prompt_sha256`。
成功时返回 201:
~~~json
{
"success": true,
"task": {
"id": "channel::upstream_task_id",
"status": "queued",
"progress": 0,
"model": "MODEL_ID",
"charged": 8.0,
"input_receipt": {
"prompt_chars": 32,
"prompt_sha256": "服务端最终提示词摘要",
"text_node_count": 1,
"reference_count": 2,
"reference_ids": ["media_image_xxx", "media_audio_xxx"],
"reference_kinds": {"image": 1, "video": 0, "audio": 1},
"reference_manifest_accepted": true
}
},
"balance": 92.0
}
~~~
### GET /api/videos/submissions/{client_submission_id}
提交请求超时或断线时,用原 `client_submission_id` 恢复已创建的任务,避免重复扣费和重复生成。恢复响应同样应核对任务的 `input_receipt`。
## 8. 查询视频状态(必须轮询)
### POST 只负责创建异步任务
`POST /api/videos` 返回 HTTP 201 时只代表任务已经被受理。下游必须保存响应中的完整 `task.id`,不能只保存上游 ID,也不能把创建响应中的 `queued` 当成永久状态。
平台统一协议响应有一层 `task` 包装:
~~~json
{
"success": true,
"task": {
"id": "channel::upstream_task_id",
"status": "queued",
"progress": 0
}
}
~~~
正确读取方式是 `body.task.id` 和 `body.task.status`。读取 `body.id` 或 `body.status` 会得到空值,常见结果就是下游界面一直停留在“生成中”。
### GET /api/videos/{task_id}
每 5 至 10 秒调用一次。任务 ID 可能包含 `::`、空格或其他字符,必须作为一个完整路径段进行 URL 编码。
~~~bash
curl -sS 'https://xpqmm.lol/api/videos/channel%3A%3Aupstream_task_id' \
-H 'Authorization: Bearer sk-xpqmm-REPLACE_ME'
~~~
查询响应同样使用 `task` 包装:
~~~json
{
"success": true,
"task": {
"id": "channel::upstream_task_id",
"status": "completed",
"progress": 100,
"video_downloading": 0,
"video_available": 1,
"error": ""
}
}
~~~
重点字段:
| JSON 路径 | 说明 |
|---|---|
| task.id | 本站完整任务 ID;后续查询必须原样使用 |
| task.status | 当前状态;不要读取响应顶层的 status |
| task.progress | 上游进度;某些上游成功前可能一直为 0 |
| task.video_downloading | 1 表示上游已成功,本站正在拉取和缓存视频 |
| task.video_available | 1 表示结果已可用,可以请求内容或下载票据 |
| task.result_url / task.url / task.video_url | 上游可能返回的结果地址;稳定下载优先使用本站内容接口或下载票据 |
| task.error | 失败原因 |
平台统一协议可能透传不同上游的状态名称。下游应使用集合判断,不要只判断一个字符串:
- 成功终态:`completed`、`complete`、`succeeded`、`success`、`finished`
- 失败终态:`failed`、`error`、`cancelled`、`canceled`
- 其他状态:继续轮询
客户端状态机:
1. `task.status` 属于失败终态:停止轮询,显示 `task.error`,允许用户重新提交。
2. `task.status` 属于成功终态,但 `task.video_downloading` 为 1 或 `task.video_available` 为 0:显示“生成成功,视频正在缓存”,继续轮询。
3. `task.video_available` 为 1:停止状态轮询,获取 `/api/videos/{task_id}/download-ticket` 或访问 `/content`。
4. 其余状态:显示生成中,5 至 10 秒后继续查询。
5. 查询遇到 429、502 或网络超时:不要把任务改为失败;按 `Retry-After` 或退避时间重试。
6. 结果默认保留 24 小时,过期后可能返回 410。
本站后端会扫描上游任务,但这不会替代下游自己的状态轮询。下游只有持续查询任务接口,才能把自己的订单状态从“生成中”更新为成功或失败。
### OpenAI 兼容轮询
如果创建接口使用 `POST /v1/videos`,查询也必须使用 `GET /v1/videos/{video_id}`。该协议响应是扁平对象,直接读取 `body.id` 和 `body.status`,状态固定为 `queued`、`in_progress`、`completed`、`failed`。不要把 `/api/videos` 的嵌套解析方式用于 `/v1/videos`,也不要混用两套查询地址。
## 9. 预览和下载视频
### GET /api/videos/{task_id}/content
直接访问用于流式预览。增加 download=1 可尝试下载;源文件尚未完整时可能返回 502,此时继续查询任务状态。
### GET /api/videos/{task_id}/download-ticket
推荐先取得短期下载票据:
~~~json
{
"success": true,
"url": "https://xpqmm.lol/...signed-download...",
"filename": "video.mp4",
"expires_in": 900
}
~~~
票据地址 15 分钟内有效,可在不暴露 API Key 的情况下交给浏览器下载。
## 10. 查询任务历史
### GET /api/tasks?limit=50
limit 最大为 100。响应 data.items 包含任务 ID、类型、平台、状态、进度、模型、错误、创建时间、结果地址、生成参数,以及视频缓存大小、缓存时间、过期时间、重试次数和缓存错误等字段。
## 11. Python 完整轮询示例
~~~python
import os
import time
from urllib.parse import quote
import requests
BASE = 'https://xpqmm.lol'
HEADERS = {'Authorization': f"Bearer {os.environ['XPQMM_API_KEY']}"}
SUCCESS = {'completed', 'complete', 'succeeded', 'success', 'finished'}
FAILED = {'failed', 'error', 'cancelled', 'canceled'}
payload = {
'client_submission_id': 'client-20261113-0001',
'model': 'MODEL_ID',
'prompt': '镜头缓慢推进,人物自然眨眼',
'references': [],
'seconds': 15,
'resolution': '720p',
'aspect_ratio': '16:9',
}
created_response = requests.post(
f'{BASE}/api/videos', headers=HEADERS, json=payload, timeout=60
)
created_response.raise_for_status()
created_body = created_response.json()
if not created_body.get('success') or not isinstance(created_body.get('task'), dict):
raise RuntimeError(created_body.get('message') or '创建视频任务失败')
task_id = created_body['task']['id']
encoded_task_id = quote(task_id, safe='')
deadline = time.monotonic() + 2 * 60 * 60
while time.monotonic() < deadline:
response = requests.get(
f'{BASE}/api/videos/{encoded_task_id}', headers=HEADERS, timeout=30
)
if response.status_code in (429, 502):
time.sleep(int(response.headers.get('Retry-After', '10')))
continue
response.raise_for_status()
body = response.json()
task = body.get('task') if isinstance(body, dict) else None
if not body.get('success') or not isinstance(task, dict):
raise RuntimeError(body.get('message') or '查询视频任务失败')
status = str(task.get('status') or '').lower()
if status in FAILED:
raise RuntimeError(task.get('error') or f'视频任务失败:{status}')
if task.get('video_available'):
ticket_response = requests.get(
f'{BASE}/api/videos/{encoded_task_id}/download-ticket',
headers=HEADERS,
timeout=30,
)
ticket_response.raise_for_status()
print(ticket_response.json()['url'])
break
phase = '视频缓存中' if status in SUCCESS else '生成中'
print(phase, status, task.get('progress', 0))
time.sleep(10)
else:
raise TimeoutError(f'轮询超时,任务仍保留:{task_id}')
~~~
## 12. JavaScript 完整轮询示例
服务端 JavaScript/Node.js 示例。不要把 API Key 写进公开浏览器代码。
~~~javascript
const base = 'https://xpqmm.lol';
const apiKey = process.env.XPQMM_API_KEY;
const headers = {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
};
const successStatuses = new Set(['completed', 'complete', 'succeeded', 'success', 'finished']);
const failedStatuses = new Set(['failed', 'error', 'cancelled', 'canceled']);
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
async function readJson(response) {
const body = await response.json().catch(() => ({}));
if (!response.ok || body.success === false) {
const error = new Error(body.message || `HTTP ${response.status}`);
error.status = response.status;
error.retryAfter = Number(response.headers.get('retry-after') || 10);
throw error;
}
return body;
}
async function createAndPollVideo(payload) {
const createdBody = await readJson(await fetch(`${base}/api/videos`, {
method: 'POST',
headers,
body: JSON.stringify({...payload, client_submission_id: crypto.randomUUID()}),
}));
// 平台协议是嵌套响应:必须读取 createdBody.task.id。
const taskId = createdBody.task?.id;
if (!taskId) throw new Error('创建响应缺少 task.id');
const encodedTaskId = encodeURIComponent(taskId);
const deadline = Date.now() + 2 * 60 * 60 * 1000;
while (Date.now() < deadline) {
let body;
try {
body = await readJson(await fetch(`${base}/api/videos/${encodedTaskId}`, {
headers: {Authorization: `Bearer ${apiKey}`},
cache: 'no-store',
}));
} catch (error) {
if (error.status === 429 || error.status === 502) {
await sleep(error.retryAfter * 1000);
continue;
}
throw error;
}
// 查询响应也是嵌套响应:状态在 body.task.status,不在 body.status。
const task = body.task;
if (!task) throw new Error('查询响应缺少 task');
const status = String(task.status || '').toLowerCase();
if (failedStatuses.has(status)) {
throw new Error(task.error || `视频任务失败:${status}`);
}
if (task.video_available) {
const ticket = await readJson(await fetch(
`${base}/api/videos/${encodedTaskId}/download-ticket`,
{headers: {Authorization: `Bearer ${apiKey}`}},
));
return {task, downloadUrl: ticket.url};
}
console.log(successStatuses.has(status) ? '视频缓存中' : '生成中', status, task.progress ?? 0);
await sleep(10_000);
}
throw new Error(`轮询超时,任务仍保留:${taskId}`);
}
const result = await createAndPollVideo({
model: 'MODEL_ID',
prompt: '镜头缓慢推进,人物自然眨眼',
references: [],
seconds: 15,
resolution: '720p',
aspect_ratio: '16:9',
});
console.log(result.downloadUrl);
~~~
### 常见的“网站已成功、下游仍在生成中”原因
1. 只读取了创建响应,没有继续调用查询接口。
2. 平台协议错误读取 `body.status`;正确字段是 `body.task.status`。
3. 只判断 `completed`,没有兼容 `succeeded`、`success`、`complete`、`finished`。
4. 查询时使用了上游任务 ID,而不是创建响应返回的完整 `task.id`。
5. 没有 URL 编码包含 `::` 的任务 ID。
6. 创建使用 `/api/videos`,查询却误用 `/v1/videos/{id}`,或者反过来。
7. 遇到一次网络错误、429 或 502 后永久停止轮询,却没有把订单标记为失败或继续重试。
## 13. 图片与视频模型节点目录
画布和模型广场中的图片、视频模型均以 `GET /api/models` 返回的当前可用目录为准。该接口按当前 API Key 的可用权限和客户价格仅返回已上线模型;模型上架、下架、改名或价格调整后,下游重新读取即可获取最新信息。公开文档页面使用 `/api/catalog/models` 自动生成实时目录;不要在下游写死离线模型清单。
~~~bash
curl -sS 'https://xpqmm.lol/api/models' \
-H 'Authorization: Bearer sk-xpqmm-REPLACE_ME'
~~~
响应结构:
~~~json
{
"success": true,
"data": [
{
"id": "MODEL_ID",
"name": "模型显示名称",
"type": "video",
"duration": "4-15",
"resolution": "480p,720p",
"resolutions": ["480p", "720p"],
"aspect_ratio": "16:9/9:16",
"aspect_ratios": ["16:9", "9:16"],
"duration_rule": {"type": "range", "min": 4, "max": 30, "unit": "second"},
"max_image_refs": 9,
"max_video_refs": 3,
"max_audio_refs": 3,
"max_total_refs": 15,
"reference_input": "media_id",
"reference_upload_endpoint": "/api/media",
"price": 6.0,
"price_unit": "task",
"resolution_prices": {"480p": 6.0, "720p": 9.0},
"pricing_options": [
{"resolution": "480p", "video_reference": false, "price": 6.0, "price_unit": "task"},
{"resolution": "720p", "video_reference": true, "price": 12.0, "price_unit": "task"}
]
}
]
}
~~~
图片模型的 `type` 为 `image`,视频模型的 `type` 为 `video`。接口可能同时返回其他类型;下游应按 `type` 分类,而不是依赖模型名称猜测类型。用 `name` 展示节点名称,用 `id` 作为图片或视频生成请求中的 `model` 值。不要将上游模型名、上游成本或上游售价作为下游模型名或客户价格展示;面向客户的价格使用本接口返回的 `price`、`price_unit` 和 `resolution_prices`。
~~~javascript
const response = await fetch('https://xpqmm.lol/api/models', {
headers: {Authorization: `Bearer ${apiKey}`},
cache: 'no-store',
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.message || '读取模型目录失败');
const imageNodes = result.data.filter(model => model.type === 'image');
const videoNodes = result.data.filter(model => model.type === 'video');
// 节点标题显示 model.name;提交请求时使用 model.id。
~~~
创建图片任务时,`model` 必须取自图片节点的完整 `id`;创建视频任务时,`model` 必须取自视频节点的完整 `id`。提交前按 `resolutions`、`duration_rule`、`aspect_ratios`、`max_*_refs` 校验参数,并从 `pricing_options` 选择与分辨率及视频参考状态一致的价格。模型不可用或变体返回 `effective_enabled=false` 时重新读取目录,不要继续使用缓存的停用模型或停用规格。