图像
POST /v1/generations
创建一个异步生成任务。积分立即预留，任务失败时退回。
请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <API 密钥> |
| Idempotency-Key | 是 | 每个请求唯一（≤ 128 字符）。用同一个 key 重发会返回原来的任务（200），不会再次扣费。同一个 key 配不同请求体 → 422。 |
| Content-Type | 是 | application/json |
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
| model | string | 必填。来自 GET /v1/models 的模型 id，例如 "nanobanana"。 |
| prompt | string | 除非提供了 images，否则必填。1–2000 个字符（个别模型上限更低——见 max_prompt）。 |
| negative_prompt | string | 选填。要避开的内容。仅在 schema 中带 negative_prompt: true 的模型上可用。 |
| n | integer | 生成张数，1–4，默认 1。每张单独计费。 |
| resolution | string | 1K（默认）· 2K · 4K。模型出图的档位，也是计价单位。模型在 params_schema.resolutions 中列出它支持的档位。 |
| ratio | string | 宽高比：auto · 1:1（默认）· 16:9 · 9:16 · 4:3 · 3:4 · 3:2 · 2:3 · 5:4 · 4:5 · 21:9。比例不影响价格。 |
| images | string[] | 选填。用于图生图的参考图，需为公开的 https URL。数量不超过模型的 max_images；模型 schema 中没有该字段表示不接受参考图。 |
| seed | integer | 选填。模型支持时，相同 seed 加相同提示词可得到可复现的结果。 |
| webhook_url | string | 选填。任务完成时回调的 https URL。见「Webhook」。 |
| size | string (legacy) | 已废弃。形如 宽x高 的字符串，会映射到最接近的 resolution + ratio。仅为兼容既有接入而保留；与 resolution 或 ratio 同时发送会返回 400。新代码请使用 resolution 和 ratio。 |
响应 202 Accepted
{"id": "…", "model": "nanobanana", "status": "queued", "params": {…}, "cost": 2, "created_at": "…"}请求体上限 64 KB。未知字段会被拒绝并返回 400.
GET /v1/generations/{id}
返回该任务。当 status = succeeded 时，响应会包含 images[]，其中是预签名下载 URL（有效期 15 分钟；再次调用可获取新 URL）。
| status | 含义 |
|---|---|
| queued | 等待工作进程接手。 |
| running | 生成中。 |
| succeeded | 已完成；带 images[]；积分已扣除。 |
| failed | 失败；带 error{code,message}；积分已退回。 |
| cancelled | 在开始前被你取消；积分已退回。 |
Failed job
{"id": "…", "status": "failed", "error": {"code": "content_policy", "message": "the prompt was rejected by the content policy"}, "cost": 2, …}对话补全同样以 generation 记录存储：记录里带 capability: "text.chat" 和一个 usage 块，包含 token 数——从不包含消息本身，只有最后一条用户消息不超过 200 字符的预览和一个哈希。
Chat completion record
{"id": "…", "model": "qwen3.8-max", "capability": "text.chat", "status": "succeeded", "params": {"prompt": "Explain idempotency keys…", "messages": 2, "messages_sha256": "9f2c…", "max_tokens": 200, "stream": true}, "usage": {"prompt_tokens": 31, "completion_tokens": 58, "total_tokens": 89, "finish_reason": "stop", "usage_source": "estimated"}, "cost": 0.004, "created_at": "…", "finished_at": "…"}GET /v1/generations
最新的在前，每页 50 条。把上一次响应里的 cursor 传回来即可取下一页。
curl -s "https://api.genmux.tech/v1/generations?cursor=2026-08-28T20:01:12.345Z" -H "Authorization: Bearer $API_KEY"Response
{"data": [ {…job…}, … ], "next_cursor": "2026-08-27T09:12:44.001Z"}用 ?capability=text.chat 按类型过滤（或 image.generate）。
DELETE /v1/generations/{id}
取消仍处于 queued 的任务并退回其积分。已经在执行的任务无法取消（409).
curl -s -X DELETE https://api.genmux.tech/v1/generations/<id> -H "Authorization: Bearer $API_KEY"Response · 200 OK
{"id": "…", "status": "cancelled", …}