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": {}
}