图片接入文档

通过建龙统一网关接入 OpenAI Images、OpenAI Responses、Gemini 和 Grok 图片模型。文档中的示例均使用脱敏令牌，响应中的图片 URL 和 Base64 内容仅作格式示例。

<JIANLONG_API_BASE_URL> 示例为 https://newapi.jianlong.it；<JIANLONG_API_TOKEN> 为控制台创建的客户端令牌。不要把令牌写入前端、代码仓库或日志。

1. 文档概览

建龙图片网关统一负责令牌鉴权、渠道选择、模型路由、计费和错误包装。客户端可以按模型支持的协议提交请求，也可以使用 OpenAI 兼容入口降低接入成本。图片生成通常是同步请求，服务端在响应中直接返回图片 URL 或 Base64；具体耗时取决于模型和尺寸。

2. 鉴权与基础约定

Bearer 鉴权

Authorization: Bearer <JIANLONG_API_TOKEN>
Content-Type: application/json

除 /v1/images/edits 外，JSON 请求均使用 Content-Type: application/json。图片编辑请求使用 multipart/form-data，不要手动设置 boundary。

查看模型

curl "<JIANLONG_API_BASE_URL>/v1/models" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>"

{
  "object": "list",
  "data": [
    {"id": "gpt-image-2", "object": "model"},
    {"id": "gemini-3-pro-image-preview", "object": "model"},
    {"id": "grok-imagine-image", "object": "model"}
  ]
}

模型列表以当前令牌实际返回为准。不同分组可见的模型不同，不能仅凭文档中的示例名称判断令牌是否有权限。

3. 模型与协议选择

模型清单

协议映射

模型名称不是协议名称。接入前优先调用 /v1/models，再根据目标模型选择入口：

4. 通用参数

尺寸与质量

尺寸、质量和透明背景并非所有模型都同时支持。网关会将兼容字段转换到渠道格式；不支持的组合会返回 400，而不是保证静默生效。

参考图片

OpenAI Images 编辑接口直接接收本地媒体文件，不需要先上传素材库。Responses 和 Gemini 若要求 URL，则使用可被上游访问的 HTTPS URL 或对应的 inline data。参考图应为 PNG、JPEG 或 WebP，并遵守当前渠道的文件大小限制。

5. OpenAI Images API

5.1 文生图

POST /v1/images/generations

curl -X POST "<JIANLONG_API_BASE_URL>/v1/images/generations" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只白色陶瓷杯放在深色木桌上，清晨侧光，写实产品摄影",
    "size": "1024x1024",
    "quality": "high",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'

请求字段

5.2 图片编辑

POST /v1/images/edits，请求为 multipart。字段 image 是本地文件，提示词和普通参数为表单字段。

curl -X POST "<JIANLONG_API_BASE_URL>/v1/images/edits" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" \
  -F "model=gpt-image-2" \
  -F "prompt=保留人物脸部和姿态，将背景替换为樱花公园，春日自然光" \
  -F "image=@./reference.png" \
  -F "size=1024x1536" \
  -F "quality=high" \
  -F "output_format=png" \
  -F "n=1"

5.3 响应格式

{
  "created": 1789814557,
  "data": [
    {
      "url": "https://.../generated-image.png",
      "revised_prompt": "..."
    }
  ],
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 21,
    "output_tokens": 272,
    "total_tokens": 293
  }
}

当返回 b64_json 而不是 url 时，字段位于 data[].b64_json，内容不包含 data:image/png;base64, 前缀时，客户端需要自行补上 MIME 前缀。

6. OpenAI Responses 图片工具

POST /v1/responses。适合已使用 OpenAI Responses SDK 的客户端。图片生成通过 tools 声明，不要把 image_generation 当作普通聊天文本。

6.1 请求示例

curl -X POST "<JIANLONG_API_BASE_URL>/v1/responses" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": "生成一张极简白色建筑的建筑摄影图，午后硬光",
    "tools": [{
      "type": "image_generation",
      "size": "1024x1024",
      "quality": "high",
      "background": "opaque",
      "output_format": "png"
    }]
  }'

6.2 响应与取图

{
  "id": "resp_01J...",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "image_generation_call",
      "id": "ig_01J...",
      "status": "completed",
      "result": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {"input_tokens": 18, "output_tokens": 280, "total_tokens": 298}
}

Responses 的图片结果常见于 output[].result，可能是 Base64；客户端应同时兼容 data[].url、data[].b64_json 和 output[].result。如果请求使用流式模式，监听图片生成完成事件后再读取最终结果。

7. Gemini 图片协议

7.1 OpenAI 兼容入口

POST /v1/chat/completions。Gemini 图片模型通过消息内容触发图片输出。部分兼容客户端把图片作为 content part 返回，必须按类型筛选，不要只读取 message.content 的纯文本。

curl -X POST "<JIANLONG_API_BASE_URL>/v1/chat/completions" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "messages": [{
      "role": "user",
      "content": "生成一张夜晚霓虹街道的电影感插画，16:9 横构图"
    }],
    "size": "1536x1024"
  }'

多模态参考图

{
  "model": "gemini-3-pro-image-preview",
  "messages": [{"role":"user","content":[
    {"type":"text","text":"把这张图改成水彩风格，保留主体构图"},
    {"type":"image_url","image_url":{"url":"https://example.com/reference.png"}}
  ]}]
}

URL 必须能被上游访问。若 SDK 支持 inline data，可使用 data:image/png;base64,...；不要把需要登录才能访问的本地 URL 直接传给上游。

7.2 Gemini 原生入口

POST /v1beta/models/{model}:generateContent

curl -X POST "<JIANLONG_API_BASE_URL>/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: <JIANLONG_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{
      "text": "生成一张红苹果放在白色桌面上的写实静物图"
    }]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

如果网关部署将 Gemini 原生请求统一为 Bearer 鉴权，应优先使用 Authorization: Bearer；仅在网关明确开启 Google 原生兼容时使用 x-goog-api-key。

7.3 响应格式

{
  "candidates": [{
    "content": {"parts": [
      {"text": "已生成图片"},
      {"inlineData": {
        "mimeType": "image/png",
        "data": "iVBORw0KGgoAAA..."
      }}
    ]},
    "finishReason": "STOP"
  ]
}

兼容入口也可能返回 OpenAI 风格的 choices[].message.content，其中图片 part 的类型可能是 image_url、inline_data 或 image。解析器应同时处理这几种结构。

8. Grok 图片生成

Grok Imagine 图片模型使用 OpenAI Images 兼容入口，但可用参数以当前 Grok 渠道为准。当前模型包括 grok-imagine-image 和 grok-imagine-image-quality。

8.1 请求示例

curl -X POST "<JIANLONG_API_BASE_URL>/v1/images/generations" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "a cinematic editorial portrait in a rainy city, 16:9",
    "n": 1,
    "response_format": "url"
  }'

建议先使用最小请求验证模型可用，再逐步增加 size、quality 或参考图参数。Grok 渠道没有可用媒体账号时，网关会返回 grok_media_no_eligible_account，这不是客户端 JSON 格式错误。

8.2 响应格式

{
  "created": 1789814557,
  "data": [{
    "url": "https://.../grok-generated.png",
    "revised_prompt": "..."
  }]
}

9. 错误响应与排查

{
  "error": {
    "message": "可读的错误描述",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

10. 限制、安全与检查清单

• 所有请求都必须使用 HTTPS；生产环境不要在浏览器前端长期保存高权限令牌。
• 图片编辑的本地文件直接提交给 /v1/images/edits；视频素材上传接口不是图片接口的必经步骤。
• 图片 URL 结果应尽快下载到自己的对象存储；上游 URL 可能有有效期。
• 不要把完整令牌、完整图片 URL、Base64 内容写入日志或工单。
• 同一个提示词每次生成可能不同；当前接口不承诺可复现的 seed 参数，不能把 seed 当作通用协议字段。
• 上线前检查：/v1/models 可见目标模型、最小文生图成功、参考图编辑成功、URL/Base64 两种结果均可解析、错误响应能被正确展示。

最小验收命令

curl -sS "<JIANLONG_API_BASE_URL>/v1/models" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" | jq '.data[].id'

curl -sS -X POST "<JIANLONG_API_BASE_URL>/v1/images/generations" \
  -H "Authorization: Bearer <JIANLONG_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"a red apple","size":"1024x1024","n":1}' \
  | jq '{created,data: [.data[] | {url,b64_json,revised_prompt}],usage}'