Gemini-3-Pro Official 이미지 생성
Generate images using Google Gemini 3 Pro official direct-connect model with native parameter control
중국 본토 사용자 안내: 중국 본토 사용자는 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-officialmodel 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_KEYBody
modelstring본문필수기본값: gemini-3-pro-image-preview-officialImage generation model name
Example: "gemini-3-pro-image-preview-official"
promptstring본문필수Text description for image generation
sizestring본문Image aspect ratio
Supported formats:
1:1- Square3:2/2:33:4/4:34:5/5:49:16/16:921:9
ninteger본문기본값: 1Number 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본문기본값: noneGoogle 검색 그라운딩. 활성화하면 모델이 생성 전에 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 onlyALLOW_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
응답
idstringUnique task identifier for querying task status
objectstringObject type, always generation.task
modelstring모델 name used
statusstringTask status
queued- Queued for processingin_progress- Processingcompleted- Successfully completedfailed- Failed
progressintegerTask progress percentage (0-100)
created_atintegerTask creation timestamp (Unix timestamp)
metadataobjectTask 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": {}
}