gemini-3-pro-image-preview

Google Gemini 3 Pro image preview — async high-quality image generation up to 4K with two channels (default + official).

Async high-quality image generation. One endpoint covers text-to-image and image-to-image with up to 14 reference images. Two channels share the same parameter shape:

gemini-3-pro-image-preview — default channel.
gemini-3-pro-image-preview-official — Google's official endpoint.

Async processing — POST returns a task_id, poll GET /api/v1/tasks/{id} for the result.
OpenAI-compatible /api/v1/images/generations envelope (text-to-image / image-to-image).
10 ratios via size; three resolution tiers (1K / 2K / 4K) via resolution.
Up to 14 reference images via image_urls — public HTTP(S) URLs only.
Up to 4 images per request via n.
Failed / moderated requests are not charged.

Quick example

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "ancient castle beneath a starry sky, cinematic",
    "size": "16:9",
    "resolution": "2K"
  }'

import requests

resp = requests.post(
    "https://reapi.ai/api/v1/images/generations",
    headers={
        "Authorization": "Bearer rk_live_xxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-3-pro-image-preview",
        "prompt": "ancient castle beneath a starry sky, cinematic",
        "size": "16:9",
        "resolution": "2K",
    },
    timeout=30,
)
print(resp.json())

const r = await fetch("https://reapi.ai/api/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-3-pro-image-preview",
    prompt: "ancient castle beneath a starry sky, cinematic",
    size: "16:9",
    resolution: "2K",
  }),
});
console.log(await r.json());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model":      "gemini-3-pro-image-preview",
        "prompt":     "ancient castle beneath a starry sky, cinematic",
        "size":       "16:9",
        "resolution": "2K",
    })
    req, _ := http.NewRequest("POST",
        "https://reapi.ai/api/v1/images/generations", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer rk_live_xxx")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

Submit response

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gemini-3-pro-image-preview",
  "status": "processing",
  "created_at": 1735000000
}

Hold onto id and poll GET /api/v1/tasks/{id} until completion.

Endpoint

POST /api/v1/images/generations    # submit a job
GET  /api/v1/tasks/{id}            # poll for the result

Async — submit returns a task_id immediately; the actual image arrives via the polling endpoint. Polling is free.

Authentication

Bearer token, minted at reapi.ai/settings/apikeys.

Authorization: Bearer rk_live_xxx

Body

`model`

string · required

One of:

"gemini-3-pro-image-preview" — default channel.
"gemini-3-pro-image-preview-official" — Google's official endpoint.

`prompt`

string · required

Detailed prompts produce better results. English and Chinese both supported. Don't restate the ratio in the prompt — pass it via size.

Image-to-image is no exception — the prompt describes what to do with the reference. Sending image_urls without a prompt returns 400.

`size`

string · default "1:1" (text-to-image) / inherited (image-to-image)

Output ratio. One of these 10 values:

1:1   2:3   3:2   3:4   4:3
4:5   5:4   9:16  16:9  21:9

Anything outside the list is rejected with 400.

When image_urls is provided without size, the output inherits the first reference image's resolution (image-to-image mode). Pass size to force a specific ratio.

`resolution`

string · default "1K"

1K / 2K / 4K. Case-insensitive — "2K" and "2k" are equivalent.

`n`

integer · default 1

1 – 4 images per request. Must be a number, not a string.

Reference images for image-to-image. Up to 14 entries. Each entry must be a public HTTP(S) URL — data: / base64 payloads are rejected at the gateway. Upload to your own object storage (S3 / R2 / OSS) and pass the URL.

Use cases

1. Text-to-image (minimal)

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "ancient castle beneath a starry sky, cinematic"
  }'

2. Text-to-image at 2K

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "neon-lit Tokyo street in the rain, cyberpunk",
    "size": "16:9",
    "resolution": "2K"
  }'

3. Text-to-image at 4K

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "cinematic mountain valley at golden hour",
    "size": "21:9",
    "resolution": "4K"
  }'

4. Image-to-image (single reference)

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "convert this snapshot into a film-grain editorial shot",
    "image_urls": ["https://your-cdn.com/photo.jpg"],
    "resolution": "2K"
  }'

5. Multi-reference fusion

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "blend the subject from photo A with the lighting of photo B",
    "size": "4:3",
    "resolution": "2K",
    "image_urls": [
      "https://your-cdn.com/photo-a.jpg",
      "https://your-cdn.com/photo-b.jpg"
    ]
  }'

6. Force the official channel

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview-official",
    "prompt": "marble bust of a philosopher, dramatic side lighting",
    "size": "1:1",
    "resolution": "2K"
  }'

Response

POST returns immediately with status: "processing"; poll GET /api/v1/tasks/{id} until status is completed or failed. Both responses share the same envelope — the output field is null until the task finishes.

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gemini-3-pro-image-preview",
  "status": "processing",
  "created_at": 1735000000
}

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gemini-3-pro-image-preview",
  "status": "completed",
  "created_at": 1735000000,
  "output": {
    "image_urls": ["https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/0.png"]
  },
  "error": null
}

URLs are stable for 7 days. Download to your own storage if you need them longer.

{
  "error": {
    "code": 20003,
    "message": "gemini-3-pro-image-preview: invalid resolution \"8K\"",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 10003,
    "message": "API key invalid",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 30001,
    "message": "Insufficient credits",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 50001,
    "message": "Rate limit exceeded",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 60099,
    "message": "Internal error — please retry",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

Upstream errors (502 / 503)

reAPI does not surface raw upstream 5xx codes to the caller. When the upstream provider returns 502 Bad Gateway, 503 Service Unavailable, or a connection failure, the worker retries up to 5 attempts with exponential backoff (~30s total budget). If all retries fail, the task ends with one of these reapi-specific error codes (returned via GET /api/v1/tasks/{id} as error.code):

reapi code	Meaning	Origin
`80001`	`provider_submit_failed`	Upstream `5xx` / network on submit
`80002`	`provider_polling_timeout`	Wall-clock cap reached while polling
`80003`	`provider_failed`	Upstream returned a terminal failure

See Errors catalog for the full code list.

Polling

`status`	Meaning
`processing`	Submitted, still generating
`completed`	`output.image_urls` is ready
`failed`	See `error.code`; not charged

Recommended cadence:

0–30s:  wait before the first poll
30s–3m: poll every 3–5s
3m+:    back off to 10s; cap at 30s

A 1K image typically completes in 30 – 60 seconds; 2K adds ~30s; 4K can take 90 – 120 seconds.

gemini-2.5-flash-image-preview — faster, cheaper variant (1K only).
gemini-3.1-flash-image-preview — newer variant with extreme ratios and Google search grounding.
Errors catalog
Authentication
Quickstart
Pricing — gemini-3-pro-image-preview

Async high-quality image generation. One endpoint covers text-to-image and image-to-image with up to 14 reference images. Two channels share the same parameter shape:

gemini-3-pro-image-preview — default channel.
gemini-3-pro-image-preview-official — Google's official endpoint.

Async processing — POST returns a task_id, poll GET /api/v1/tasks/{id} for the result.
OpenAI-compatible /api/v1/images/generations envelope (text-to-image / image-to-image).
10 ratios via size; three resolution tiers (1K / 2K / 4K) via resolution.
Up to 14 reference images via image_urls — public HTTP(S) URLs only.
Up to 4 images per request via n.
Failed / moderated requests are not charged.

Quick example

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "ancient castle beneath a starry sky, cinematic",
    "size": "16:9",
    "resolution": "2K"
  }'

import requests

resp = requests.post(
    "https://reapi.ai/api/v1/images/generations",
    headers={
        "Authorization": "Bearer rk_live_xxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-3-pro-image-preview",
        "prompt": "ancient castle beneath a starry sky, cinematic",
        "size": "16:9",
        "resolution": "2K",
    },
    timeout=30,
)
print(resp.json())

const r = await fetch("https://reapi.ai/api/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-3-pro-image-preview",
    prompt: "ancient castle beneath a starry sky, cinematic",
    size: "16:9",
    resolution: "2K",
  }),
});
console.log(await r.json());

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "model":      "gemini-3-pro-image-preview",
        "prompt":     "ancient castle beneath a starry sky, cinematic",
        "size":       "16:9",
        "resolution": "2K",
    })
    req, _ := http.NewRequest("POST",
        "https://reapi.ai/api/v1/images/generations", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer rk_live_xxx")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    out, _ := io.ReadAll(resp.Body)
    fmt.Println(string(out))
}

Submit response

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gemini-3-pro-image-preview",
  "status": "processing",
  "created_at": 1735000000
}

Hold onto id and poll GET /api/v1/tasks/{id} until completion.

Endpoint

POST /api/v1/images/generations    # submit a job
GET  /api/v1/tasks/{id}            # poll for the result

Async — submit returns a task_id immediately; the actual image arrives via the polling endpoint. Polling is free.

Authentication

Bearer token, minted at reapi.ai/settings/apikeys.

Authorization: Bearer rk_live_xxx

Body

`model`

string · required

One of:

"gemini-3-pro-image-preview" — default channel.
"gemini-3-pro-image-preview-official" — Google's official endpoint.

`prompt`

string · required

Detailed prompts produce better results. English and Chinese both supported. Don't restate the ratio in the prompt — pass it via size.

Image-to-image is no exception — the prompt describes what to do with the reference. Sending image_urls without a prompt returns 400.

`size`

string · default "1:1" (text-to-image) / inherited (image-to-image)

Output ratio. One of these 10 values:

1:1   2:3   3:2   3:4   4:3
4:5   5:4   9:16  16:9  21:9

Anything outside the list is rejected with 400.

When image_urls is provided without size, the output inherits the first reference image's resolution (image-to-image mode). Pass size to force a specific ratio.

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "ancient castle beneath a starry sky, cinematic"
  }'

2. Text-to-image at 2K

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "neon-lit Tokyo street in the rain, cyberpunk",
    "size": "16:9",
    "resolution": "2K"
  }'

3. Text-to-image at 4K

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "cinematic mountain valley at golden hour",
    "size": "21:9",
    "resolution": "4K"
  }'

4. Image-to-image (single reference)

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "convert this snapshot into a film-grain editorial shot",
    "image_urls": ["https://your-cdn.com/photo.jpg"],
    "resolution": "2K"
  }'

5. Multi-reference fusion

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "blend the subject from photo A with the lighting of photo B",
    "size": "4:3",
    "resolution": "2K",
    "image_urls": [
      "https://your-cdn.com/photo-a.jpg",
      "https://your-cdn.com/photo-b.jpg"
    ]
  }'

6. Force the official channel

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3-pro-image-preview-official",
    "prompt": "marble bust of a philosopher, dramatic side lighting",
    "size": "1:1",
    "resolution": "2K"
  }'

Response

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gemini-3-pro-image-preview",
  "status": "processing",
  "created_at": 1735000000
}

{
  "id": "task_018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e",
  "model": "gemini-3-pro-image-preview",
  "status": "completed",
  "created_at": 1735000000,
  "output": {
    "image_urls": ["https://cdn.reapi.ai/media/tasks/018f5a3a1b6e7d9f8c2b4d6e8f0a2c4e/0.png"]
  },
  "error": null
}

URLs are stable for 7 days. Download to your own storage if you need them longer.

{
  "error": {
    "code": 20003,
    "message": "gemini-3-pro-image-preview: invalid resolution \"8K\"",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 10003,
    "message": "API key invalid",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 30001,
    "message": "Insufficient credits",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 50001,
    "message": "Rate limit exceeded",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

{
  "error": {
    "code": 60099,
    "message": "Internal error — please retry",
    "request_id": "req_8a4f0d2e-1c8b-4f1a-9e2d-3b7c5a6f0a1b"
  }
}

Upstream errors (502 / 503)

reapi code	Meaning	Origin
`80001`	`provider_submit_failed`	Upstream `5xx` / network on submit
`80002`	`provider_polling_timeout`	Wall-clock cap reached while polling
`80003`	`provider_failed`	Upstream returned a terminal failure

See Errors catalog for the full code list.

Polling

`status`	Meaning
`processing`	Submitted, still generating
`completed`	`output.image_urls` is ready
`failed`	See `error.code`; not charged

Recommended cadence:

0–30s:  wait before the first poll
30s–3m: poll every 3–5s
3m+:    back off to 10s; cap at 30s

A 1K image typically completes in 30 – 60 seconds; 2K adds ~30s; 4K can take 90 – 120 seconds.

gemini-2.5-flash-image-preview — faster, cheaper variant (1K only).
gemini-3.1-flash-image-preview — newer variant with extreme ratios and Google search grounding.
Errors catalog
Authentication
Quickstart
Pricing — gemini-3-pro-image-preview

gemini-3-pro-image-preview

Table of Contents

gemini-3-pro-image-preview

Table of Contents