> ## 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.1 Flash Image VIP 이미지 생성

> Gemini 3.1 Flash Image VIP 는 텍스트-이미지와 이미지-이미지를 지원하며 참조 이미지는 최대 14장입니다.

> [!NOTE]
>
> **중국 본토 사용자 안내:** 중국 본토 사용자는 `https://toapis.cn` 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 `https://toapis.com` 을 `https://toapis.cn` 로 바꿔 주세요.

## 버전 선택

| 버전 | 참조 이미지 상한 | 사용 사례 |
| - | - | - |
| [일반 버전](https://docs.toapis.com/docs/ko/api-reference/images/gemini-3.1-flash/generation.md) | 6장 | 텍스트-이미지와 소량 참조 이미지 편집 |
| [VIP](https://docs.toapis.com/docs/ko/api-reference/images/gemini-3.1-flash-vip/generation.md) | 14장 | 더 많은 참조 이미지가 필요한 편집과 조합 |
| [Official](https://docs.toapis.com/docs/ko/api-reference/images/gemini-3.1-flash-official/generation.md) | 14장 | 원본 생성 파라미터 제어가 필요할 때 |

참조 이미지 수는 입력 이미지 총수를 의미하며 출력 이미지 수를 뜻하지 않습니다. 세 버전은 서로 다른 모델 ID를 사용하므로 해당 페이지의 파라미터와 예시에 따라 호출하세요.

## 현재 버전

`model: "gemini-3.1-flash-image-preview-vip"` 로 VIP 를 선택하며 텍스트-이미지와 최대 14장 참조 이미지의 이미지-이미지 또는 이미지 편집을 지원합니다.
참조 이미지 7\~14장이 필요한 편집이나 다중 이미지 조합에 적합합니다. 다중 이미지 요청에서는 목록 순서대로 각 이미지의 용도를 설명할 수 있습니다.
요청은 비동기로 실행되며 제출에 성공하면 작업 ID로 결과를 조회합니다.

> [!WARNING]
>
> `image_urls` 는 이미지 URL 만 지원하고 base64 를 직접 받지 않습니다. 먼저 [Upload 이미지 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 로 접근 가능한 URL 을 받으세요.

## Authorizations

**Authorization** `string` *required*

`Bearer YOUR_API_KEY` 로 인증합니다. API Key 는 [콘솔](https://toapis.com/dashboard/tokens) 에서 생성할 수 있습니다.

## Body

**model** `string` *required* (default: gemini-3.1-flash-image-preview-vip)

`gemini-3.1-flash-image-preview-vip` 로 고정합니다. 일반 모델명과 다른 별칭은 이 VIP 라우트로 자동 전환되지 않습니다.

**prompt** `string` *required*

생성하거나 편집할 이미지를 설명합니다. 참조 이미지를 여러 장 전달할 때는 목록 순서대로 각 이미지의 용도를 설명할 수 있습니다.

**size** `string`

이미지 화면 비율입니다. 예: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.

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

요청당 이미지 1장을 생성합니다. 숫자 `1` 을 사용하고 문자열 `"1"` 은 사용하지 마세요.

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

선택 사항인 참조 이미지 목록이며 최대 14장입니다. 텍스트-이미지 생성 시에는 이 필드를 생략합니다.
먼저 [Upload 이미지 API](https://docs.toapis.com/docs/ko/api-reference/uploads/images.md) 로 접근 가능한 이미지 URL 을 받고 base64 를 직접 전달하지 마세요.

**참조 이미지 필드**

**url** `string` *required*

공개적으로 접근 가능한 HTTP 또는 HTTPS 이미지 URL 입니다.

예시: `[{"url": "https://example.com/reference-1.png"}, {"url": "https://example.com/reference-2.png"}]`.
14장은 입력 참조 이미지 상한이며 한 번의 요청에서 출력되는 이미지 수가 아닙니다.

**metadata** `object`

**출력 해상도**

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

`1K`, `2K`, `4K` 를 지원합니다. 생략하면 `1K` 를 사용합니다.

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

Google 검색 그라운딩. 활성화하면 모델이 생성 전에 Google을 검색하며, 결과의 `grounding_metadata`에 인용 출처가 포함될 수 있습니다.

옵션:

* `none` - 비활성화 (기본값)
* `web` - 웹 검색
* `image` - 이미지 검색
* `web_image` - 웹 + 이미지 검색

실제로 실행된 검색 쿼리당 과금되며 \$0.014/쿼리입니다. 요청 제출 시 최대 4개 쿼리의 보증금이 예약되고, 사용하지 않은 부분은 정산 시 환불됩니다.

## 요청 예시

```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.1-flash-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": "1K"}
  }'
```

예시의 URL 을 실제로 접근 가능한 참조 이미지 주소로 바꾸세요. 참조 이미지를 계속 추가할 수 있지만 목록 총 개수는 14장을 넘을 수 없습니다.
텍스트-이미지 요청은 `image_urls` 만 제거하고 프롬프트를 수정하면 됩니다.

## 결과 조회

제출 응답의 `id` 가 작업 ID 입니다. [이미지 작업 상태 조회](https://docs.toapis.com/docs/ko/api-reference/tasks/image-status.md) 로 상태와 최종 이미지를 가져오세요.
작업 조회와 [Webhook 콜백](https://docs.toapis.com/docs/ko/api-reference/webhooks/task-webhooks.md) 은 공통 비동기 이미지 API 규약을 따릅니다.


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