图像生成与编辑 API

最近更新：2026 年 10 月 17 日（Asia/Shanghai）
关联：帮助中心 · 大模型 API · 视频生成

本文说明如何调用词源探索的文生图与改图能力。若只是让模型「看图、理解图」，请看大模型 API · 多模态，不要用本页接口。

1. 选择协议

词源探索当前明确面向生图的模型是 Gemini 图像系列：

gemini-3-pro-image
gemini-3.1-flash-image

协议	路径	说明
Gemini 原生（推荐）	`POST https://ai.afp.net/v1beta/models/{model}:generateContent`	参数最贴近 Gemini 图像能力，适合生产批量
OpenAI Images 兼容	`POST https://ai.afp.net/v1/images/generations`、`/v1/images/edits`	复用 OpenAI SDK；可用模型以 `/v1/models` 与控制台「支持端点」为准

INFO

请勿假定平台上架了 gpt-image-*、dall-e-* 或 Imagen :predict 模型。若控制台未列出，请勿编造模型名调用。生图请优先使用上述 *-image 模型。

鉴权：OpenAI 路径用 Authorization: Bearer sk-xxx；Gemini 原生推荐 x-goog-api-key: sk-xxx（也可用 Bearer）。

警告

保护好 API Key，勿写入前端、截图或公开仓库。

2. 查询模型

bash

curl "$CIYUAN_BASE_URL/v1/models" \
  -H "Authorization: Bearer $CIYUAN_API_KEY"

在返回列表中查找 gemini-3-pro-image、gemini-3.1-flash-image，以及控制台标注支持 images/generations 的其它模型（若有）。价格见控制台定价页。

3. Gemini 原生：文生图

bash

curl "$CIYUAN_BASE_URL/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "一只坐在窗边看雨的橘猫，水彩风格"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

返回的 candidates[0].content.parts[] 中，带 inlineData（mimeType + Base64 data）的部分即为图片。

python

# pip install -U google-genai
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["CIYUAN_API_KEY"],
    http_options=types.HttpOptions(base_url=os.environ["CIYUAN_BASE_URL"]),
)

resp = client.models.generate_content(
    model="gemini-3-pro-image",
    contents="一只坐在窗边看雨的橘猫，水彩风格",
    config=types.GenerateContentConfig(response_modalities=["TEXT", "IMAGE"]),
)
for part in resp.candidates[0].content.parts:
    if part.inline_data:
        with open("cat.png", "wb") as f:
            f.write(part.inline_data.data)
    elif part.text:
        print(part.text)

常用 generationConfig 字段（视模型支持情况）：

字段	说明
`responseModalities`	建议 `["TEXT","IMAGE"]`
`imageConfig.aspectRatio`	如 `1:1`、`16:9`、`9:16`、`3:4`、`4:3`
`imageConfig.imageSize`	如部分模型支持的 `1K` 等语义尺寸
`candidateCount`	候选数量；最终以实际返回为准，请遍历数组

4. Gemini 原生：改图 / 参考图

在 parts 中同时放入参考图（inlineData）与文字指令即可：

bash

IMAGE_BASE64="$(base64 -w0 reference.png 2>/dev/null || base64 < reference.png | tr -d '\n')"

curl "$CIYUAN_BASE_URL/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [{
      \"role\": \"user\",
      \"parts\": [
        {\"inlineData\": {\"mimeType\": \"image/png\", \"data\": \"$IMAGE_BASE64\"}},
        {\"text\": \"把背景换成雪景，保持主体构图不变，生成一张新图，不要原样复制参考图\"}
      ]
    }],
    \"generationConfig\": {
      \"responseModalities\": [\"TEXT\", \"IMAGE\"],
      \"imageConfig\": {\"aspectRatio\": \"1:1\"}
    }
  }"

提示词中写清「生成新图、不要原样复制」，可减少「几乎等于参考图」的结果。

5. OpenAI Images 兼容接口

bash

curl "$CIYUAN_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $CIYUAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<控制台标注支持 images/generations 的模型>",
    "prompt": "一只坐在窗边看雨的橘猫，水彩风格",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

python

from openai import OpenAI
import base64
from pathlib import Path

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://ai.afp.net/v1",
)
result = client.images.generate(
    model="<支持 images/generations 的模型>",
    prompt="一只坐在窗边看雨的橘猫，水彩风格",
    size="1024x1024",
    n=1,
    response_format="b64_json",
)
Path("image.png").write_bytes(base64.b64decode(result.data[0].b64_json))

编辑接口：POST https://ai.afp.net/v1/images/edits（multipart/form-data 或 JSON）。用 curl -F 或标准 multipart 库，不要手写 Content-Type boundary。

注意：

同步等待生成完成，结果只在本次响应中；请及时落盘。过久可能 504 task_timeout。
n 是输出张数；multipart 里的 image[] 是输入参考图，含义不同。
若用 Gemini 图像模型走 OpenAI 兼容封装，部分 OpenAI 专属字段（如某些 style、background=transparent、moderation 非 auto 等）可能无效或报错——把风格要求写进 prompt 更稳妥。
也可用 /v1/chat/completions 调用 *-image 模型，但图片落在 content 的形式（Markdown / Data URL 等）依赖平台版本；批量生产请用 Gemini 原生。

6. 本页 FAQ

没有返回图片怎么办？
检查 parts 是否含 inlineData；可能被安全策略过滤，或只返回了文本。降低敏感/版权向描述后重试。

一次能生成多张吗？
OpenAI 路径用 n；Gemini 原生用 candidateCount。务必遍历返回数组，不要只读第一张。

改图几乎等于参考图？
在 prompt 中明确「重组生成新图，不要复制参考图」。

multipart 报「请求体格式错误」或 NextPart: EOF？
多为 boundary/请求体被中间件破坏。改用 curl -F 或官方 SDK，避免手写 multipart。

能用 Imagen :predict 吗？
仅当控制台与 /v1/models 确实提供对应模型时才可尝试。当前文档不以 Imagen 为主路径。

计费怎么算？
按次或按规格，以控制台定价与「使用日志」为准；本文不列数字。

上一页：大模型 API · 下一页：视频生成

图像生成与编辑 API ​

1. 选择协议 ​

2. 查询模型 ​

3. Gemini 原生：文生图 ​

4. Gemini 原生：改图 / 参考图 ​

5. OpenAI Images 兼容接口 ​

6. 本页 FAQ ​

图像生成与编辑 API

1. 选择协议

2. 查询模型

3. Gemini 原生：文生图

4. Gemini 原生：改图 / 参考图

5. OpenAI Images 兼容接口

6. 本页 FAQ