接口地址: https://hajimi.165201.xyz. 使用本站 API Key 鉴权. 下载 OpenAPI 定义.
鉴权与幂等
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY
每次新的生成任务使用一个新的幂等键, 同一次任务的重试使用原键. 同一账号、同一幂等键和相同请求内容返回原任务, 不重复生成和扣费. 同键对应不同请求内容时返回 HTTP 409. 查询与取回需使用提交任务的原密钥. API Key 不得放入公开页面或日志.
异步提交
POST /v1/image-requests. 必须提供 Idempotency-Key. endpoint 填原出图路径, request 填原请求内容, 模型价格、权限与原出图接口一致.
curl https://hajimi.165201.xyz/v1/image-requests \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-20261104-0001' \
-d '{
"endpoint": "/v1beta/models/gemini-3-pro-image-cbj:generateContent",
"request": {
"contents": [{"role":"user","parts":[{"text":"画一只猫"}]}],
"generationConfig": {"responseModalities":["TEXT","IMAGE"]}
}
}'
接受任务后返回 HTTP 202. 返回体的 data.request_id 用于后续查询, Location 响应头提供查询路径. HTTP 202 表示任务已接受, 实际费用以 billing 为准.
{
"success": true,
"data": {
"request_id": "img_...",
"generation_status": "queued",
"delivery_status": "waiting",
"billing": {"status":"pending","amount":null,"currency":"CNY"},
"status_url": "/v1/image-requests/img_...",
"result_url": null
}
}
支持的原出图路径包括 Gemini generateContent、streamGenerateContent, 以及 /v1/images/generations、图片模型的 /v1/chat/completions 和携带 image_generation 工具的 /v1/responses.
查询状态和取回结果
| 接口 | 作用 |
GET /v1/image-requests/{request_id} | 查询单个任务的生成、发送和计费状态. |
GET /v1/image-requests/{request_id}/result | 取回原始出图响应. 生成中返回 HTTP 202, 完成后返回原协议的图片响应, 过期返回 HTTP 410. 取回不会再次生成或扣费. |
GET /v1/image-requests?idempotency_key={key} | 提交请求时未收到任务 ID, 可按原幂等键查找. |
GET /v1/image-requests | 查询当前密钥最近 100 条图片任务. |
curl https://hajimi.165201.xyz/v1/image-requests/img_... \
-H 'Authorization: Bearer YOUR_API_KEY'
curl https://hajimi.165201.xyz/v1/image-requests/img_.../result \
-H 'Authorization: Bearer YOUR_API_KEY' \
-o image-result.json
建议间隔 2 秒查询一次, 优先遵循响应中的 Retry-After. generation_status=completed 后取回图片; billing.status=pending 时费用仍在结算, 继续查询账单状态.
| 字段 | 取值 | 含义 |
| generation_status | queued / running / completed / failed / unconfirmed / expired | 等待生成 / 生成中 / 已生成有效图片 / 生成失败 / 正在核实结果 / 原结果已过期. |
| delivery_status | waiting / sent / interrupted | 等待发送或取回 / 已向调用方写出结果 / 接收连接中断. |
| billing.status | pending / charged / not_charged | 待结算 / 已扣费 / 未扣费. |
| billing.amount | 金额字符串或 null | 实际金额, 单位为人民币元; 待结算时为 null. |
| result_expires_at | Unix 时间戳或 null | 原结果保存期限. 原始图片响应自完成起保存 1 小时. |
| message | 中文说明 | 展示生成和费用事实. 程序判断请使用状态字段. |
保留原出图接口
原出图接口继续按原协议返回. 请求增加 Idempotency-Key 后, 断线重试可命中原任务. 增加 Prefer: respond-async 后, 原接口也会返回 HTTP 202 和任务信息. 正常出图响应包含 X-Nanbei-Request-Id 和 Location.
计费和重试
请求提交生成后, 客户端超时、断开连接或主动取消接收, 不会终止已经开始的生成任务. 本站完成有效图片生成后, 按原价格正常扣费. 未生成有效图片不收取图片生成费用. 同一任务重复查询和取回不重复扣费; 使用新的幂等键提交新的生成任务会产生新的生成费用.
任务为 running、unconfirmed 或费用为 pending 时, 先查询原任务, 避免立即更换幂等键重发. 任务为 failed 后可根据中文原因调整参数、模型或稍后重试.
未出图原因
| 上游原因 | 中文含义 |
| IMAGE_SAFETY / SAFETY | 生成结果或内容触发上游安全审核, 未返回图片. |
| PROHIBITED_CONTENT | 提示词或输入内容被上游内容安全审核拒绝. |
| IMAGE_RECITATION | 上游因图片复现或版权相关限制停止生成. |
| MAX_TOKENS | 达到最大输出长度时图片尚未完成. |
| IMAGE_OTHER / OTHER | 上游因其他原因停止生成, 未说明更具体的原因. |
| NO_IMAGE / STOP | 上游结束响应时没有返回图片, 未给出安全审核结论. |
错误的中文说明会保留上述原因, 在 upstream_reason 可用时同时返回上游原因码. billing 仍按实际账本状态返回.
错误返回
鉴权失败返回 HTTP 401, 请求格式错误返回 HTTP 400, 幂等键冲突返回 HTTP 409, 查询不存在或无权读取的任务返回 HTTP 404. 出图错误保留原协议结构, message 为中文, code 或 Gemini 的 reason 为稳定错误码.
{"error":{"code":"IDEMPOTENCY_CONFLICT","message":"该幂等键已用于不同的请求内容, 请核对请求或使用新的幂等键."},"request_id":"img_..."}