Cubicspaces API

简体中文

English

简体中文

English

Appearance

Gemini Image ​

Gemini Image 通过 OpenAI 兼容的 Chat Completions 接口调用。客户端只需要请求 Cubicspaces 的 /v1/chat/completions，把 model 设置为 Gemini 图片模型即可。

公开接入统一使用 OpenAI 兼容格式：

  • 请求图片尺寸和比例时，把 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
}

不要这样写：

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);

注意事项 ​

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

Copyright © 2026-present Cubicspaces