Cubicspaces API

简体中文

English

简体中文

English

Appearance

Gemini Image ​

Gemini 图片模型支持两种接入方式：OpenAI 兼容的 Chat Completions 接口，以及 Gemini 原生格式的 generateContent 接口。两种接口的请求字段和图片返回位置不同，不能混用。

OpenAI 兼容接入 ​

通过 /v1/chat/completions 调用时：

  • 请求图片尺寸和比例时，把 image_config 放在请求体顶层。
  • image_config 内使用 snake_case 字段：aspect_ratio、image_size。
  • 不需要传 Gemini 原生的 generationConfig.imageConfig。
  • 不要在请求 JSON 里放 extra_body.google.image_config；该写法不是公开文档推荐格式。

请求地址 ​

http
POST /v1/chat/completions

支持模型 ​

模型说明
gemini-3-pro-image-previewGemini 3 Pro 图片预览模型
gemini-3.1-flash-image-previewGemini 3.1 Flash 图片预览模型

实际可用模型以账户权限和平台配置为准。

请求示例 ​

bash
curl https://cubicspaces.cloud/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": "生成一张猫在咖啡馆里的图片，暖色调，写实摄影风格"
      }
    ],
    "image_config": {
      "aspect_ratio": "1:1",
      "image_size": "2K"
    },
    "stream": false
  }'

请求参数 ​

参数类型必填说明
modelstring是Gemini 图片模型名称，例如 gemini-3.1-flash-image-preview
messagesarray是OpenAI Chat Completions 消息数组
streamboolean否图片生成建议传 false 或省略
image_configobject否顶层图片配置，用于指定比例和尺寸

响应格式 ​

图片会返回在 OpenAI Chat Completions 响应的 choices[0].message.images 中：

json
{
  "id": "chatcmpl_123",
  "object": "chat.completion",
  "model": "gemini-3.1-flash-image-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "images": [
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,BASE64_IMAGE_DATA"
            },
            "index": 0
          }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

如果模型同时返回文本和图片，content 中是文本部分，images 中是生成图片。客户端应从 choices[].message.images[].image_url.url 读取图片数据。

不要从 content 中解析 Markdown 图片。Cubicspaces 会把上游可能返回的图片数据统一整理到 message.images，content 只保留文本内容。

图片配置 ​

image_config 是可选参数，必须放在请求体顶层，不能放在 messages、请求 JSON 的 extra_body 字段或 Gemini 原生字段内。支持字段：

字段类型说明
aspect_ratiostring图片比例，例如 1:1、16:9、9:16
image_sizestring图片尺寸，例如 1K、2K、4K

正确写法：

json
{
  "model": "gemini-3.1-flash-image-preview",
  "messages": [
    {
      "role": "user",
      "content": "生成一张猫在咖啡馆里的图片"
    }
  ],
  "image_config": {
    "aspect_ratio": "16:9",
    "image_size": "4K"
  },
  "stream": false
}

在 OpenAI 兼容接口中不要这样写：

json
{
  "generationConfig": {
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "4K"
    }
  }
}

上面是 Gemini 原生请求字段，不适用于 Cubicspaces 的 OpenAI 兼容 /v1/chat/completions 入口。

SDK 示例 ​

部分 OpenAI SDK 会限制可传入的顶层参数。遇到这种情况时，使用 SDK 提供的 extra_body / raw body 选项把 image_config 合并到最终请求体顶层。注意：这里的 extra_body 是 SDK 选项，不是发送给接口的 JSON 字段。

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://cubicspaces.cloud/v1"
)

response = client.chat.completions.create(
    model="gemini-3.1-flash-image-preview",
    messages=[
        {"role": "user", "content": "生成一张猫在咖啡馆里的图片"}
    ],
    extra_body={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "2K",
        }
    },
    stream=False
)

print(response.choices[0].message.images[0].image_url.url)
js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://cubicspaces.cloud/v1"
});

const response = await client.chat.completions.create({
  model: "gemini-3.1-flash-image-preview",
  messages: [
    { role: "user", content: "生成一张猫在咖啡馆里的图片" }
  ],
  image_config: {
    aspect_ratio: "1:1",
    image_size: "2K"
  },
  stream: false
});

console.log(response.choices[0].message.images[0].image_url.url);

注意事项 ​

  • 使用 OpenAI Chat Completions 格式时，不要在请求体中传 Gemini 原生字段。
  • image_config 是顶层字段，字段名是 aspect_ratio 和 image_size，不是 aspectRatio 和 imageSize。
  • 图片结果在 message.images 内以 data:image/...;base64,... URL 形式返回。
  • content 只作为文本内容读取，不作为图片输出位置。
  • 图片生成建议使用非流式请求，便于客户端一次性读取完整图片内容。

Gemini 原生格式接入 ​

通过 Cubicspaces 的 Gemini 原生接口调用时，模型名称放在 URL 中，请求体使用 contents 和 generationConfig，返回体保持 Gemini 原生结构。使用 Cubicspaces API Key，通过 x-goog-api-key 请求头鉴权。

http
POST /v1beta/models/{model}:generateContent

文生图 ​

bash
curl "https://cubicspaces.cloud/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "生成一张猫在咖啡馆里的图片，暖色调，写实摄影风格"}]
      }
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

参考图生图 ​

在同一个 contents[].parts 中放入文字和参考图。将 BASE64_INPUT_IMAGE 替换为图片文件的纯 Base64 内容（不含 data:image/...;base64, 前缀），并按实际文件类型填写 mimeType。多张参考图可增加多个 inlineData part；模型对参考图数量及大小的限制以实际可用模型为准。

json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "保持参考图主体，改成清晨自然光的摄影风格"},
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "BASE64_INPUT_IMAGE"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
  }
}

读取图片 ​

原生响应中的文字与图片都位于 candidates[].content.parts[]。图片 part 的 inlineData.data 是纯 Base64，inlineData.mimeType 是文件类型；不应按 OpenAI 兼容接口的 choices[].message.images 读取。

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "已生成图片。"},
          {"inlineData": {"mimeType": "image/png", "data": "BASE64_OUTPUT_IMAGE"}}
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

原生接口的 imageConfig 使用 aspectRatio、imageSize，不要传 OpenAI 兼容入口的顶层 image_config。更多原生字段参见 Gemini 原生协议。

Copyright © 2026-present Cubicspaces