POST images

Generate Images

November 17, 2025 (November 20, 2025)

Request Headers
Request Body
Responses
Model
Examples
Try It

Generate images using AI models Imagen 4, Nano Banana / Gemini 2.5 Flash Image, and Nano Banana Pro / Gemini 3 Pro Image from text prompts with optional reference images.

This endpoint features dynamic concurrency management, allowing anywhere from 3 to 20 parallel generations depending on real-time capacity. If you receive a 429 Too Many Requests or 503 Service Unavailable response, simply wait 5-10 seconds before retrying—both status codes indicate temporary capacity constraints and are safe to retry. If you consistently receive 429 errors, you may need to execute a cool-off period of at least a few hours before trying again. Image generation typically completes within 10-20 seconds.

Important notes:

Nano Banana Pro model: The nano-banana-pro model is only available with Google AI Ultra accounts. Attempting to use this model with non-Ultra accounts will result in a 429 error with reason PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED.
Nano Banana model: The nano-banana model is primarily designed for image editing with context references. When used with text prompts only (no reference images), it may produce unexpected results or occasionally return HTTP 500 errors. If this occurs, try switching to imagen-4 which often successfully processes prompts that were rejected by nano-banana. You can also try to uppercase your original prompt and wrap it with “” to see if that will help. For example, this will fail: hola amigos!, whereas this will most likely pass: "HOLA AMIGOS!".
Content moderation: If your generation is moderated, retrying with the same prompt often succeeds on subsequent attempts as moderation decisions can vary between requests. Alternatively, switching between imagen-4, nano-banana, and nano-banana-pro models may help, as they have different content moderation behaviors.

Use any Google AI subscription or even free account for unlimited image generations.

https://api.useapi.net/v1/google-flow/images

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

API token is required, see Setup useapi.net for details.

Request Body

{
  "prompt": "A serene mountain landscape at sunset with vibrant colors",
  "model": "imagen-4",
  "aspectRatio": "landscape",
  "count": 4,
  "seed": 123456
}

email is optional. The email address of the Google Flow account to use.

When only one account is configured, the API will automatically use that account.

With multiple accounts configured, omitting the email parameter triggers automatic load balancing based on image generation job statistics to select the healthiest account.

If reference images (reference_1 to _3) are provided, the email parameter can be omitted—the API will automatically use the same account where the images were uploaded.
prompt is required, text description for image generation.
model is optional, the AI model to use for image generation (default: imagen-4).
Supported values: imagen-4, nano-banana, nano-banana-pro (Ultra accounts only).
aspectRatio is optional, output image aspect ratio (default: landscape).
Supported values: landscape, portrait.
count is optional, number of image variations to generate (1-4, default: 4).
seed is optional, random seed for reproducible results (integer ≥ 0).
reference_1, reference_2 and reference_3 are optional, use mediaGenerationId from POST /assets/email for reference images. Both models support max 3 reference images.
replyUrl is optional, webhook URL for job status callbacks. Receives POST requests with job status updates (created, completed, failed). The JSON payload shape matches GET /jobs/jobId response. Callbacks timeout after 5 seconds.
replyRef is optional, custom reference string passed back in webhook callbacks. Useful for tracking jobs on your end.

Auto-detection: If model is not specified and 1-3 reference images are provided, the API automatically selects nano-banana. Otherwise defaults to imagen-4.

Responses

200 OK

Images generated successfully. Returns job ID and media array with generated image data.

{
  "jobId": "j1731859345678i-u12345-email:jo***@gmail.com-bot:google-flow",
  "media": [
    {
      "name": "…redacted…",
      "workflowId": "…redacted…",
      "image": {
        "generatedImage": {
          "seed": 123456,
          "mediaGenerationId": "user:12345…redacted…",
          "mediaVisibility": "PRIVATE",
          "prompt": "A serene mountain landscape at sunset with vibrant colors",
          "modelNameType": "IMAGEN_3_5",
          "workflowId": "…redacted…",
          "fifeUrl": "https://storage.googleapis.com/…redacted…",
          "aspectRatio": "IMAGE_ASPECT_RATIO_LANDSCAPE",
          "requestData": {
            "promptInputs": [
              {
                "textInput": "A serene mountain landscape at sunset with vibrant colors"
              }
            ],
            "imageGenerationRequestData": {
              "imageGenerationImageInputs": []
            }
          }
        }
      }
    }
  ]
}

400 Bad Request

Invalid request (validation error, reference count exceeded, email mismatch, or content policy violation).

General error:

{
  "error": "Invalid request parameters"
}

Content policy error:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_UNSAFE_GENERATION"
      }
    ]
  }
}

401 Unauthorized

Invalid API token.
```
{
  "error": "Unauthorized"
}
```

402 Payment Required

Subscription expired or insufficient credits.

{
  "error": "Account has no subscription or subscription expired"
}

403 Forbidden

Unauthorized access to reference images from another user.

{
  "error": "Unauthorized access to user:123 detected in reference user:123-email:...-image:..."
}

404 Not Found

Account not found or not configured.

{
  "error": "Google Flow account [email protected] not found"
}

429 Too Many Requests

Rate limit or quota exhausted (concurrency limit or account quota reached). Wait 5-10 seconds and retry. If this persists, you may need to cool this account off for a few hours before trying again.

Concurrency/rate limit error:

{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_USER_REQUESTS_THROTTLED"
      }
    ]
  }
}

Per-model daily quota reached (e.g., using nano-banana-pro on non-Ultra account):

{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "PUBLIC_ERROR_PER_MODEL_DAILY_QUOTA_REACHED",
        "metadata": {
          "canUpgradeForQuota": "true"
        }
      }
    ]
  }
}

500 Internal Server Error

One or more generated images were moderated by Google’s content policy. Try one of the following:
- Switch to imagen-4 model (often successfully processes prompts rejected by nano-banana)
- Modify your prompt or remove/change reference images
- Retry the same request (moderation decisions can vary between attempts)
```
{
  "error": {
    "code": 500,
    "message": "Internal error encountered.",
    "status": "INTERNAL"
  }
}
```

503 Service Unavailable

Service temporarily unavailable. Wait 5-10 seconds and retry.

{
  "error": {
    "code": 503,
    "message": "Service temporarily unavailable.",
    "status": "UNAVAILABLE",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_UNAVAILABLE"
      }
    ]
  }
}

596 Session Error

Google session refresh failed. The account cookies needs to be updated following the instructions in Setup Google Flow.
```
{
  "error": "Failed to refresh session."
}
```

Model

jobId - Unique job identifier (for use with GET /jobs/jobId)
media - Array of generated images (1-4 images based on count)
media[].image.generatedImage - Generated image data object
generatedImage.fifeUrl - Direct signed URL to access the generated image (valid for limited time)
generatedImage.seed - Seed used for this generation (for reproducibility)
generatedImage.mediaGenerationId - mediaGenerationId for use in subsequent API calls
generatedImage.prompt - The prompt used for generation
generatedImage.modelNameType - Model variant used (IMAGEN_3_5, R2I, GEM_PIX)
generatedImage.aspectRatio - Generated image aspect ratio (IMAGE_ASPECT_RATIO_LANDSCAPE or IMAGE_ASPECT_RATIO_PORTRAIT)
generatedImage.mediaVisibility - Visibility setting (always “PRIVATE”)
generatedImage.workflowId - Unique workflow identifier
generatedImage.requestData - Request data used for this generation including prompt inputs and reference images
media[].name - Internal identifier for the media item
media[].workflowId - Unique workflow identifier for this generation

{
  jobId: string                         // Job identifier
  media: Array<{
    name: string                    // Internal media identifier
    workflowId: string              // Unique workflow ID
    image: {
      generatedImage: {
        seed: number
        mediaGenerationId: string   // Format: user:{userid}-email:{hex}-image:{id}
        mediaVisibility: string     // "PRIVATE"
        prompt: string
        modelNameType: string       // "IMAGEN_3_5" | "R2I" | "GEM_PIX"
        workflowId: string
        fifeUrl: string             // Direct signed URL to generated image
        aspectRatio: string         // "IMAGE_ASPECT_RATIO_LANDSCAPE" | "IMAGE_ASPECT_RATIO_PORTRAIT"
        requestData: {
          promptInputs: Array<{
            textInput: string
          }>
          imageGenerationRequestData: {
            imageGenerationImageInputs: Array<{
              mediaGenerationId: string
              imageInputType: string  // "IMAGE_INPUT_TYPE_REFERENCE"
            }>
          }
        }
      }
    }
  }>
  error?: string | {                // Error: string (useapi.net) or object (Google API)
    code: number
    message: string
    status: string
    details: Array<{
      '@type': string
      reason: string
      metadata?: {
          canUpgradeForQuota: boolean
        }
    }>
  }
}

Examples

curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "prompt": "A serene mountain landscape at sunset with vibrant colors",
       "model": "imagen-4",
       "aspectRatio": "landscape",
       "count": 4,
       "seed": 123456
     }' \
     "https://api.useapi.net/v1/google-flow/images" > response.json

# Download images using fifeUrl
curl -o image_1.jpg "$(cat response.json | jq -r '.media[0].image.generatedImage.fifeUrl')"
curl -o image_2.jpg "$(cat response.json | jq -r '.media[1].image.generatedImage.fifeUrl')"
# Continue for remaining images...

const token = 'YOUR_API_TOKEN';
const apiUrl = 'https://api.useapi.net/v1/google-flow/images';

const response = await fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A serene mountain landscape at sunset with vibrant colors',
    model: 'imagen-4',
    aspectRatio: 'landscape',
    count: 4,
    seed: 123456
  })
});

const result = await response.json();
console.log('Generated images:', result.media.length);

// Download and save images
for (const [index, item] of result.media.entries()) {
  const img = item.image.generatedImage;
  console.log(`Image ${index + 1} seed:`, img.seed);
  console.log(`mediaGenerationId:`, img.mediaGenerationId);

  // Download image from fifeUrl
  const imageResponse = await fetch(img.fifeUrl);
  const imageBlob = await imageResponse.blob();

  // In Node.js with fs:
  // const buffer = Buffer.from(await imageBlob.arrayBuffer());
  // require('fs').writeFileSync(`generated_image_${index + 1}.jpg`, buffer);

  // In browser: create download link or display in <img> element
  // const url = URL.createObjectURL(imageBlob);
  // document.querySelector('img').src = url;
}

import requests

token = 'YOUR_API_TOKEN'
api_url = 'https://api.useapi.net/v1/google-flow/images'

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json'
}

data = {
    'prompt': 'A serene mountain landscape at sunset with vibrant colors',
    'model': 'imagen-4',
    'aspectRatio': 'landscape',
    'count': 4,
    'seed': 123456
}

response = requests.post(api_url, headers=headers, json=data)
result = response.json()

print(f"Generated {len(result['media'])} images")

# Download and save images
for index, item in enumerate(result['media']):
    img = item['image']['generatedImage']
    print(f"Image {index + 1} seed:", img['seed'])
    print(f"mediaGenerationId:", img['mediaGenerationId'])

    # Download image from fifeUrl
    image_response = requests.get(img['fifeUrl'])
    with open(f'generated_image_{index + 1}.jpg', 'wb') as f:
        f.write(image_response.content)