XPQMM API在线文档

图片与视频生成 API 文档

完整接口说明与全部模型目录

协议对接

下游服务可直接通过 HTTPS 调用 XPQMM API。使用你自己的 API Key;模型 ID 和面向客户的价格以实时模型目录为准。

Base URL: https://xpqmm.lol鉴权: Bearer API Key输出: JSON / 异步任务
GEThttps://xpqmm.lol/api/models
POSThttps://xpqmm.lol/api/media
POSThttps://xpqmm.lol/api/media/validate
POSThttps://xpqmm.lol/api/videos
GEThttps://xpqmm.lol/api/videos/{task_id}
GEThttps://xpqmm.lol/api/videos/{task_id}/download-ticket
POSThttps://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,数量或提示词摘要不一致时不要继续。

实时已上架模型

页面每次打开都会从服务端读取,只显示当前已上架的图片和视频模型。下游提交时使用卡片中的公开模型 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` 时重新读取目录,不要继续使用缓存的停用模型或停用规格。