> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 3 Pro Image VIP Image Generation

> Gemini 3 Pro Image VIP supports text-to-image and image-to-image generation with up to 14 reference images.

> [!NOTE]
>
> **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.

## Version Options

| Version | Reference image limit | Use case |
| - | - | - |
| [Standard](https://docs.toapis.com/docs/en/api-reference/images/gemini-3-pro-image/generation.md) | 6 | Text-to-image and edits with a small number of reference images |
| [VIP](https://docs.toapis.com/docs/en/api-reference/images/gemini-3-pro-image-vip/generation.md) | 14 | Edits and compositions that need more reference images |
| [Official](https://docs.toapis.com/docs/en/api-reference/images/gemini-3-pro-image-official/generation.md) | 14 | When you need native generation parameter control |

The reference image count is the total number of input images; it does not represent the number of output images. The three versions use different model IDs, so follow the parameters and examples on the corresponding page.

## Current Version

Use `model: "gemini-3-pro-image-preview-vip"` to select VIP, which supports text-to-image and image-to-image or image editing with up to 14 reference images.
It suits edits or multi-image compositions that need 7 to 14 reference images. In multi-image requests, you can explain the purpose of each image in list order.
Requests run asynchronously; after a successful submission, query the result by task ID.

> [!WARNING]
>
> `image_urls` only supports image URLs and does not accept base64 directly. First use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) to get an accessible URL.

## Authorizations

**Authorization** `string` *required*

Authenticate with `Bearer YOUR_API_KEY`. Create an API Key in the [console](https://toapis.com/dashboard/tokens).

## Body

**model** `string` *required* (default: gemini-3-pro-image-preview-vip)

Fixed to `gemini-3-pro-image-preview-vip`. The standard model name and other aliases do not automatically switch to this VIP route.

**prompt** `string` *required*

Describe the image to generate or edit. When you pass multiple reference images, you can explain the purpose of each image in list order.

**size** `string`

Image aspect ratio, for example `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.

**n** `integer` (default: 1)

Generates 1 image per request. Use the number `1`, not the string `"1"`.

**image\_urls** `object[]`

Optional list of reference images, up to 14. Omit this field for text-to-image.
First use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) to get an accessible image URL; do not pass base64 directly.

**Reference image fields**

**url** `string` *required*

A publicly accessible HTTP or HTTPS image URL.

Example: `[{"url": "https://example.com/reference-1.png"}, {"url": "https://example.com/reference-2.png"}]`.
14 is the limit for input reference images, not the number of output images from a single request.

**metadata** `object`

**Output resolution**

**resolution** `string` (default: 2K)

Supports `1K`, `2K`, `4K`. When omitted, `2K` is used.

**grounding** `string` (default: none)

Google Search grounding. When enabled, the model searches Google before generating; the result may include cited sources in `grounding_metadata`.

Options:

* `none` - Disabled (default)
* `web` - Web search

Billed per executed search query at \$0.014 per query. A deposit of up to 4 queries is reserved when the request is submitted, and unused queries are refunded at settlement.

## Request Example

```bash theme={null}
curl --request POST 'https://toapis.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gemini-3-pro-image-preview-vip",
    "prompt": "Keep the person from the first image, adopt the background and color palette from the second image, and generate a natural-light portrait.",
    "size": "1:1",
    "n": 1,
    "image_urls": [
      {"url": "https://example.com/reference-1.png"},
      {"url": "https://example.com/reference-2.png"}
    ],
    "metadata": {"resolution": "2K"}
  }'
```

Replace the example URLs with reference image addresses that are actually reachable. You can keep adding reference images, but the total number in the list must not exceed 14.
For a text-to-image request, simply remove `image_urls` and change the prompt.

## Querying Results

The `id` in the submit response is the task ID. Use the [Image Task Status endpoint](https://docs.toapis.com/docs/en/api-reference/tasks/image-status.md) to get the status and the final image.
Task queries and [Webhook callbacks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md) follow the same conventions as the general async image endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.