图片请求 API 对接

图片请求记录

接口地址: 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_statusqueued / running / completed / failed / unconfirmed / expired等待生成 / 生成中 / 已生成有效图片 / 生成失败 / 正在核实结果 / 原结果已过期.
delivery_statuswaiting / sent / interrupted等待发送或取回 / 已向调用方写出结果 / 接收连接中断.
billing.statuspending / charged / not_charged待结算 / 已扣费 / 未扣费.
billing.amount金额字符串或 null实际金额, 单位为人民币元; 待结算时为 null.
result_expires_atUnix 时间戳或 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_..."}