图像生成与编辑

积木的图像接口与 OpenAI Images API 兼容，支持文生图（generations）与图像编辑（edits）。 鉴权见 鉴权与令牌（统一使用 Authorization: Bearer <令牌>）， 通用错误码见 错误处理与请求追踪。

端点总览

调用协议与响应形态

图像生成不止 Images 这一个入口。同一个模型可能被配置为接受下列请求协议之一， 而返回结果只有两种形态。协议决定你往哪个路径发请求，形态决定你从哪里取图。

两种响应形态的取图方式：

• OpenAI Images 结构：data[].url 或 data[].b64_json，详见下文返回形式。 Gemini 的 imagen 系列虽然上游走原生协议，但从 /v1/images/generations 调用时 网关会把结果转成这个结构（固定填 b64_json），调用方无需感知差异。
• 对话兼容格式：图片写在 choices[].message.content 里，形如 ![image](https://...) 或 ![image](data:image/png;base64,...)，需要自行从 Markdown 中解析。 即梦 jimeng 系列、部分 Flux 与 Cloudflare 模型走这条链路。

文生图

请求参数

未列出的额外字段不保证透传给上游，请以上表字段与 媒体 Schema 声明的参数为准。

尺寸约束

size 的合法取值由模型决定，传错会被上游拒绝：

返回形式

响应为 OpenAI Images 结构，data 数组长度与 n 一致：

{
  "created": 1753700000,
  "data": [
    {
      "url": "https://.../image.png",
      "b64_json": "",
      "revised_prompt": ""
    }
  ]
}

• dall-e 系列可通过 response_format 选择 url（临时链接，会过期）或 b64_json
• gpt-image 系列始终返回 b64_json，不设 response_format
• 拿到 url 形式的结果请尽快下载转存，临时链接有时效
• 响应结构以服务端实现为准：网关按 OpenAI Images 兼容结构返回，不同上游模型对 url / b64_json / revised_prompt 三个字段的填充情况可能不同，以实际返回为准

请求示例

curl https://api.jimu.chat/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIMU_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只在月球上喝茶的橘猫，水彩风格",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }'

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["JIMU_API_KEY"],
    base_url="https://api.jimu.chat/v1",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="一只在月球上喝茶的橘猫，水彩风格",
    size="1024x1024",
    quality="low",
    n=1,
)
print(result.data[0].b64_json[:80])

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.JIMU_API_KEY,
  baseURL: 'https://api.jimu.chat/v1',
})

const result = await client.images.generate({
  model: 'gpt-image-2',
  prompt: '一只在月球上喝茶的橘猫，水彩风格',
  size: '1024x1024',
  quality: 'low',
  n: 1,
})
console.log(result.data[0].b64_json?.slice(0, 80))

图像编辑

与 generations 的 JSON 请求不同，edits 使用 multipart/form-data 上传参考图：

多图输入上限由模型决定。以 gpt-image-2 为例，其媒体 Schema 声明 image_uris 最多 10 张参考图； 其他模型请以 媒体 Schema 返回的实时定义为准。

curl https://api.jimu.chat/v1/images/edits \
  -H "Authorization: Bearer $JIMU_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=把照片中的人物换成卡通风格" \
  -F "image=@./photo.png" \
  -F "size=1024x1024"

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["JIMU_API_KEY"],
    base_url="https://api.jimu.chat/v1",
)

result = client.images.edit(
    model="gpt-image-2",
    image=open("./photo.png", "rb"),
    prompt="把照片中的人物换成卡通风格",
    size="1024x1024",
)
print(result.data[0].b64_json[:80])

import fs from 'node:fs'
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.JIMU_API_KEY,
  baseURL: 'https://api.jimu.chat/v1',
})

const result = await client.images.edit({
  model: 'gpt-image-2',
  image: fs.createReadStream('./photo.png'),
  prompt: '把照片中的人物换成卡通风格',
  size: '1024x1024',
})
console.log(result.data[0].b64_json?.slice(0, 80))

对话兼容格式

部分图像模型（即梦 jimeng 系列、部分 Flux 与 Cloudflare 模型）不走 Images 端点， 而是从对话接口进入。请求体就是标准的 Chat Completions 结构， 网关负责把消息内容翻译成上游的图像请求。

请求参数

提示词与参考图的提取规则：

• 提示词取最后一条 role: "user" 消息的文本内容；若没有任何 user 消息， 则退回到最后一条含文本的消息。找不到任何文本时请求被拒绝。
• 多模态消息只取其中的 text 片段作为提示词，不会把图片描述拼进去。
• 参考图扫描全部消息中的 image_url 片段并按出现顺序去重收集， 不限于最后一条消息。这与提示词只看最后一条的规则不同，注意区分。
• 图像相关的额外参数（如尺寸、画质）可直接写在请求体顶层，会被合并后透传给上游。

{
  "model": "jimeng-3.0",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "把这张图改成水彩风格" },
        { "type": "image_url", "image_url": { "url": "https://example.com/ref.png" } }
      ]
    }
  ]
}

返回形式

响应是标准 chat.completion 结构，图片以 Markdown 内嵌在 choices[0].message.content 里，需要自行解析：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1753700000,
  "model": "jimeng-3.0",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "![image](https://.../result.png)"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2 }
}

• 上游返回链接时内嵌形式为 ![image](https://...)；返回 base64 时为 ![image](data:image/png;base64,...)。两种都可能出现，解析时都要覆盖。
• 多张图时以换行分隔，content 中会出现多个 ![image](...)。
• finish_reason 固定为 stop。
• usage 中的 token 数不是真实用量。 图像按张计费，这里的数值只是占位， 不要用它做成本估算——实际扣费以控制台账单为准。

请求示例

curl https://api.jimu.chat/v1/chat/completions \
  -H "Authorization: Bearer $JIMU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jimeng-3.0",
    "messages": [{ "role": "user", "content": "一只戴墨镜的柴犬，赛博朋克风格" }]
  }'

Gemini 原生格式

Gemini 系图像模型可以走原生协议。这条链路的响应是上游原始结构，网关不做改写， 因此取图方式与前两种格式完全不同。完整的请求体字段说明见 Gemini 原生协议，本节只讲图像相关部分。

请求参数

要让模型输出图片，generationConfig.responseModalities 需包含 "IMAGE"：

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "一只戴墨镜的柴犬，赛博朋克风格" }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "aspectRatio": "16:9" }
  }
}

上表字段名写 camelCase 或 snake_case 都可以：responseModalities / response_modalities、 imageConfig / image_config、inlineData / inline_data、mimeType / mime_type 都会被正确解析。两种写法混用也不会出错。

返回形式

图片位于 candidates[].content.parts[].inlineData，与文本段 text混在同一个 parts 数组里，需要按 part 类型分别处理：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "这是为你生成的图片：" },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUg..."
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1298
  }
}

• parts 中同时含文本与图片是常态，不要假设只有一个元素。
• data 为 base64，需配合 mimeType 自行解码落盘。
• 流式请求走 :streamGenerateContent?alt=sse，图片同样出现在增量事件的 parts[].inlineData 中。
• 上游因安全策略拦截时可能返回空 candidates 并带 promptFeedback.blockReason。

请求示例

curl "https://api.jimu.chat/v1beta/models/gemini-2.0-flash-exp:generateContent" \
  -H "x-goog-api-key: $JIMU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "role": "user", "parts": [{ "text": "一只戴墨镜的柴犬" }] }],
    "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
  }'

流式生成

gpt-image 系列支持 stream: true，响应为 SSE 事件流：

• 过程事件携带 b64_json 中间图（数量由 partial_images 控制，0–3）
• 结束事件包含最终图片与用量
• 流式模式必须 n=1，网关会在请求上游前拒绝 stream=true, n>1 的请求

计费提示

图像按张计费，尺寸与画质影响单价。以 dall-e 系列为例的计费倍率： 1024x1024 为基准 1 倍，256x256 为 0.4 倍，512x512 为 0.45 倍， 1024x1792 / 1792x1024 为 2 倍；dall-e-3 选 hd 画质时方图再乘 2， 长图（1024x1792 / 1792x1024）画质因子乘 1.5（与尺寸倍率叠加后总倍率 3）。 各模型的实际价格见控制台定价页。