ToAPIsToAPIs
Gemini-3-Pro-Image Official

Gemini-3-Pro Official 画像生成

Generate images using Google Gemini 3 Pro official direct-connect model with native parameter control

POST
/v1/images/generations

中国本土のユーザー向け: 中国本土のユーザーは https://toapis.cn を API エンドポイント(Base URL)としてご利用ください。本ドキュメント内の例では https://toapis.com を https://toapis.cn に置き換えてください。

  • Direct connection to Google Vertex AI using the Gemini 3 Pro Image native API
  • Select the gemini-3-pro-image-preview-official model via the model parameter
  • Supports text-to-image and image-to-image generation
  • Supports native generation parameters like temperature, topP, and maxOutputTokens
  • Supports resolution (1K/2K/4K), personGeneration, and imageOutputOptions image configuration
  • Supports thinkingConfig thinking mode for improved complex scene generation
  • Supports safetySettings for content safety control
  • Asynchronous task management with task ID for result querying

Important Change: For better performance and cost control, we no longer support passing base64 image data directly in image_urls. Please use the Upload Image endpoint to upload images first, then use the returned URL in this API.

Authorizations

Authorizationstringヘッダー必須

All endpoints require Bearer Token authentication

Get API Key: Visit the API Key Management page to obtain your API Key

Add to request headers:

Authorization: Bearer YOUR_API_KEY

Body

modelstringボディ必須デフォルト: gemini-3-pro-image-preview-official

Image generation model name

Example: "gemini-3-pro-image-preview-official"

promptstringボディ必須

Text description for image generation

sizestringボディ

Image aspect ratio

Supported formats:

  • 1:1 - Square
  • 3:2 / 2:3
  • 3:4 / 4:3
  • 4:5 / 5:4
  • 9:16 / 16:9
  • 21:9
nintegerボディデフォルト: 1

Number of images to generate

Fixed at 1

image_urlsstring[]ボディ

Reference image URL array for image-to-image generation or editing

⚠️ Only URL format is supported (base64 is no longer supported)

  • Publicly accessible image URLs (http:// or https://)
  • Use the Upload Image endpoint to upload local images and get URLs

Limits:

  • Maximum 14 images
  • Maximum file size per image: 10MB
  • Supported formats: .jpeg, .jpg, .png, .webp
metadataobjectボディ

Vertex AI native extension parameters

Show metadata fields
temperaturenumberボディ

Generation temperature, controls output randomness

Range: 0.0 - 2.0

topPnumberボディ

Top-P sampling parameter

Range: 0.0 - 1.0, default 0.95

maxOutputTokensintegerボディ

Maximum output tokens

Default 32768

resolutionstringボディ

Output image resolution, automatically mapped to Vertex AI native imageSize

Options: 1K, 2K, 4K, default 1K

groundingstringボディデフォルト: none

Google 検索によるグラウンディング。有効にすると、モデルは生成前に Google を検索し、結果の grounding_metadata に引用元が含まれる場合があります。

オプション:

  • none - 無効(デフォルト)
  • web - ウェブ検索

実際に実行された検索クエリごとに課金され、$0.014/クエリです。リクエスト送信時に最大 4 クエリ分のデポジットが予約され、未使用分は決済時に返金されます。

personGenerationstringボディ

Person generation control

Options:

  • ALLOW_ALL - Allow generating all people (including adults and children)
  • ALLOW_ADULT - Allow generating adults only
  • ALLOW_NONE - Disallow generating people
imageOutputOptionsobjectボディ

Image output format configuration

imageOutputOptions fields
mimeTypestringボディ

Output image format

Options: image/png, image/jpeg, image/webp

compressionQualityintegerボディ

Compression quality (JPEG only)

thinkingConfigobjectボディ

Thinking mode configuration. When enabled, the model reasons before generating images, improving results for complex scenes

thinkingConfig fields
thinkingBudgetintegerボディ

Thinking token budget, controls the depth of model reasoning

Range: 0 - 24576, default is determined by the model

thinkingLevelstringボディ

Thinking level

Options: LOW, MEDIUM, HIGH, MINIMAL

safetySettingsarrayボディ

Safety settings array for content safety filtering

safetySettings elements
categorystringボディ

Safety category

Options: HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_HARASSMENT

thresholdstringボディ

Filtering threshold

Options: OFF, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH

レスポンス

idstring

Unique task identifier for querying task status

objectstring

Object type, always generation.task

modelstring

モデル name used

statusstring

Task status

  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
progressinteger

Task progress percentage (0-100)

created_atinteger

Task creation timestamp (Unix timestamp)

metadataobject

Task metadata

リクエスト例

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3-pro-image-preview-official",
    "prompt": "A futuristic city skyline with neon lights, cyberpunk style",
    "size": "16:9",
    "n": 1,
    "metadata": {
      "temperature": 1.0,
      "topP": 0.95,
      "resolution": "2K",
      "personGeneration": "ALLOW_ALL",
      "thinkingConfig": {
        "thinkingLevel": "HIGH"
      }
    }
  }'
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json"
    },
    json={
        "model": "gemini-3-pro-image-preview-official",
        "prompt": "A futuristic city skyline with neon lights, cyberpunk style",
        "size": "16:9",
        "n": 1,
        "metadata": {
            "temperature": 1.0,
            "topP": 0.95,
            "resolution": "2K",
            "personGeneration": "ALLOW_ALL",
            "thinkingConfig": {
                "thinkingLevel": "HIGH"
            }
        }
    }
)

task = response.json()
print(f"Task ID: {task['id']}")
print(f"Status: {task['status']}")
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-ToAPIs-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gemini-3-pro-image-preview-official',
    prompt: 'A futuristic city skyline with neon lights, cyberpunk style',
    size: '16:9',
    n: 1,
    metadata: {
      temperature: 1.0,
      topP: 0.95,
      resolution: '2K',
      personGeneration: 'ALLOW_ALL',
      thinkingConfig: {
        thinkingLevel: 'HIGH'
      }
    }
  })
});

const task = await response.json();
console.log(`Task ID: ${task.id}`);
console.log(`Status: ${task.status}`);

レスポンス例

{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "gemini-3-pro-image-preview-official",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}