gemini-3.1-flash-image-preview

• 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).
• 14 ratios via size, including extreme 1:4 / 4:1 / 1:8 / 8:1.
• Four resolution tiers via resolution: 0.5K / 1K / 2K / 4K.
• Up to 14 reference images via image_urls — public HTTP(S) URLs only.
• Up to 4 images per request via n.
• Optional Google search grounding via google_search and google_image_search.

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.1-flash-image-preview",
    "prompt": "neon-lit cyberpunk skyline at midnight",
    "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.1-flash-image-preview",
        "prompt": "neon-lit cyberpunk skyline at midnight",
        "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.1-flash-image-preview",
    prompt: "neon-lit cyberpunk skyline at midnight",
    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.1-flash-image-preview",
        "prompt":     "neon-lit cyberpunk skyline at midnight",
        "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.1-flash-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.1-flash-image-preview" — default channel.
• "gemini-3.1-flash-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 14 values:

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

1:4 / 4:1 / 1:8 / 8:1 are useful for tall posters, banner ads, and long-strip social formats. Anything outside the list is rejected with 400.

resolution

string · default "1K"

0.5K / 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.

image_urls

string[] · optional

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. Recommended split: ≤ 10 object references + ≤ 4 character references for best consistency.

google_search

boolean · default false

When true, the model first searches the web for textual context to ground the generated image in real-world facts. Useful for prompts that reference recent events, named entities, or specific places. Adds an extra search round-trip — budget extra polling time.

google_image_search

boolean · default false

When true, the model also searches the web for image references in addition to text. Requires google_search: true — sending google_image_search: true with google_search: false (or omitted) returns 400.

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.1-flash-image-preview",
    "prompt": "neon-lit cyberpunk skyline at midnight"
  }'

2. Long-banner poster (extreme ratio)

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "long horizontal banner of a serene lakeside at sunrise",
    "size": "8:1",
    "resolution": "2K"
  }'

3. Tall mobile-first poster

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "vertical movie poster, lone astronaut on a frozen moon",
    "size": "1:4",
    "resolution": "2K"
  }'

4. Search-grounded generation

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "the Eiffel Tower lit up for Bastille Day fireworks",
    "size": "16:9",
    "resolution": "2K",
    "google_search": true,
    "google_image_search": true
  }'

5. Image-to-image with reference

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "stylize this product photo as a vintage magazine cover",
    "image_urls": ["https://your-cdn.com/product.jpg"],
    "size": "4:5",
    "resolution": "2K"
  }'

6. Multi-reference fusion

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "place subject from reference 1 into the scene of reference 2",
    "size": "16:9",
    "resolution": "4K",
    "image_urls": [
      "https://your-cdn.com/subject.jpg",
      "https://your-cdn.com/scene.jpg"
    ]
  }'

7. Low-cost preview at 0.5K

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer rk_live_xxx" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "concept thumbnail of a forest temple",
    "size": "1:1",
    "resolution": "0.5K",
    "n": 4
  }'

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.1-flash-image-preview",
  "status": "processing",
  "created_at": 1735000000
}

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

{
  "error": {
    "code": 20003,
    "message": "gemini-3.1-flash-image-preview: google_image_search requires google_search:true",
    "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):

See Errors catalog for the full code list.

Polling

Recommended cadence:

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

A 1K image typically completes in 10 – 30 seconds; 4K and Google search grounding both add latency.

Related

• gemini-2.5-flash-image-preview — earlier variant (1K only).
• gemini-3-pro-image-preview — higher-fidelity variant without search grounding.
• Errors catalog
• Authentication
• Quickstart
• Pricing — gemini-3.1-flash-image-preview