图像接口：生成、编辑与多种请求格式

图片接口不只有一种格式。先确定模型与线路支持哪一种，再决定请求路径和请求体。相同的 /v1/images/generations 路径，既可能接收 model + prompt，也可能接收 model + input.messages；两者不能随意混用。

请求地址与鉴权#

使用你自己的归壹 API 密钥。OpenAI 兼容与本页归壹统一入口采用 Authorization: Bearer <你的归壹 API 密钥>；Gemini 原生入口的 x-goog-api-key 写法见 Gemini 接口。JSON 请求带 Content-Type: application/json；上传文件时由客户端生成 multipart 边界。不要使用登录密码或其他平台的密钥。

1. OpenAI 风格：文字生成图片#

# 先在本地安全设置 UNIVTO_API_KEY；不要把真实值贴进文档或工单。
curl --fail-with-body 'https://univto.com/v1/images/generations' \
  -H "Authorization: Bearer $UNIVTO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"model":"替换为当前可用的Seedream模型ID","prompt":"白色背景上的一只蓝色纸鹤，简洁插画","size":"2K","response_format":"url"}'

通常从 data 数组读取结果。支持 URL 的线路可返回 data[].url；支持 Base64 的其他线路可能返回 data[].b64_json，需要按实际媒体类型解码。不要默认两者同时存在。归壹当前 Seedream 映射使用 URL 结果，不应将它改成 b64_json 来试探。图片结果和链接应及时保存，未承诺永久存储。

2. OpenAI 风格：编辑已有图片#

传统编辑接口采用 multipart/form-data，核心是 image 文件与 prompt，显式提供 model；mask、size、n 和 response_format 按目标型号选择。mask 用透明区域指定编辑位置时，尺寸需要与原图一致。文档中的 PNG、小于 4MB、方形等约束属于传统编辑合同，不能直接当成所有新图像模型的统一限制。

请求方法：POST
路径：/v1/images/edits
认证：Authorization: Bearer <你的归壹 API 密钥>
表单字段：
  model = <支持此编辑协议的模型 ID>
  image = <本地图片文件>
  prompt = 把画面中的纸鹤改成绿色
可选字段：mask、size、n、response_format

某些 Seedream 类线路接受 JSON 中的 image URL 或 data URL，而不是上述传统 multipart 请求。即使路径相同，也应使用该模型明确支持的格式。编辑成功时按返回的图片结果字段读取，不要把请求中的参考图 URL 当作生成结果。

3. 通义原生格式：生成与编辑#

这一格式将提示词放在 input.messages[].content[].text。编辑时在 content 中增加 image 图片引用；生成时不需要图片。必需字段为 model、input 与其中的 messages。parameters 可包含 negative_prompt、prompt_extend、watermark、size，编辑还可能支持 n。参数是否可用以目标型号为准。下面两段只说明协议结构，尚不作为归壹已验收线路的调用承诺。

{
  "model": "qwen-image-plus",
  "input": {
    "messages": [
      {"role": "user", "content": [{"text": "画一只蓝色纸鹤，白色背景"}]}
    ]
  },
  "parameters": {"size": "1328*1328"}
}

{
  "model": "qwen-image-edit-plus",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {"image": "https://example.com/your-image.png"},
          {"text": "保留纸鹤形状，把颜色改为绿色"}
        ]
      }
    ]
  }
}

上述接口参考使用 data 图片结果数组，但具体字段仍须按当前实际响应核对。size 中的星号尺寸是该原生格式的写法，不要直接替换 OpenAI 或 Seedream 的尺寸写法。

4. Gemini 原生格式：Nano Banana 类生图#

模型名放在路径 /v1beta/models/{model}:generateContent 中，提示词放在 contents[].parts[].text；generationConfig.responseModalities 指定输出模态。imageConfig 使用 camelCase 字段 aspectRatio、imageSize。下面示例展示结构，不保证示例型号当前已在你的归壹账号上线。

{
  "contents": [
    {"role": "user", "parts": [{"text": "画一只蓝色纸鹤，白色背景"}]}
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
  }
}

结果应遍历 candidates[].content.parts，而不只读取一段文本。图片可能位于 inlineData，按照其中的 mimeType 与 Base64 data 解码；同时处理文本部分及安全拦截、无图片输出等情况。不要把 imageSize、比例或思考参数视为所有 Gemini 图片型号均支持。

5. Gemini 图片的 OpenAI 聊天包装#

这是一种聊天包装，使用 model、messages 与 stream，而不是 /v1/images/generations。部分服务还约定 extra_body.google.image_config，字段为 snake_case。该扩展不属于所有 OpenAI 兼容服务的通用参数，归壹当前线路尚未完成这套扩展的验收。

{
  "model": "gemini-3-pro-image-preview",
  "stream": false,
  "messages": [{"role": "user", "content": "画一只蓝色纸鹤，白色背景"}],
  "extra_body": {
    "google": {"image_config": {"aspect_ratio": "1:1", "image_size": "2K"}}
  }
}

这一包装的结果可能在 choices[].message.content 中，以文本、Markdown data URL 或服务约定的图片结构表达；不能套用 data[].url 的解析方式。接口资料中有结构定义与示例不完全一致的情况，接入前应以目标线路说明和受控响应核对，不应为了凑字段而同时混入 contents 与 messages。