Image Generation

Image Generation turns a text prompt — optionally guided by reference images — into one or more images. Nine models across four families share one request schema and one set of endpoints; you pick a model with the model field.

You can call it three ways:

• Synchronous — POST /v1/images/generation blocks until the image is ready and returns the raw model output (base64 image data) in the response body.
• Asynchronous — POST /v1/images/generation/async returns a taskId immediately; poll GET /v1/images/generation/tasks/{taskId} for hosted image URLs.
• Estimate first — POST /v1/images/generation/estimate-credits returns the credit cost and whether your account can generate, without spending anything.

Choose a model

Use this table to pick a model, then open its family page for the exact limits, quirks, and examples.

gpt-image-2 is the default when model is omitted. The 10 standard ratios are 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, and 21:9 — every ratio except the four extreme ones. See Aspect ratios for the full rules.

Workflow

Request parameters

These parameters apply to POST /v1/images/generation, POST /v1/images/generation/async, and POST /v1/images/generation/estimate-credits — the three endpoints share one request schema.

¹ provider is required on the two generation endpoints and optional on estimate-credits. ² prompt is required on the two generation endpoints; on estimate-credits it may be empty or omitted (it only affects the input-token estimate).

Aspect ratios

Fourteen ratios exist across the catalogue. Ten are standard and accepted by most models; four are extreme and accepted only by gemini-3.1-flash-image and seedream-5-0-pro.

How aspectRatio is resolved, once the schema default above has not already filled it in:

Image sizes

imageConfig.imageSize accepts 1K, 2K (default), and 4K. Larger sizes cost more credits.

Do not hardcode credit costs — call estimate-credits for the exact figure for your model, size, and ratio.

Reference images

Reference images guide the generation. Supply each one as either a URL (fileData) or base64 (inlineData), never both, and keep the array within the model's limit.

The schema caps referenceImages at 14 items for every model. Families with a tighter limit reject the excess with 400 and a message naming the limit. Accepted MIME types for both fileData and inlineData are image/png, image/jpeg, image/webp, image/heic, and image/heif.

The three image endpoints accept a JSON body up to 25MB — four times the platform default, because base64 inlineData has to fit inside it. Base64 inflates a file by roughly a third, so keep inlined images under about 18MB of original bytes in total, or pass URLs with fileData instead.

Generate an image (synchronous)

POST /v1/images/generation

Generate an image and block until it is ready. The response body is the raw model output — JSON containing base64 image data, not the standard { code, message, data } envelope. See Response formats.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider: 'google',
      model: 'gemini-3-pro-image',
      prompt: 'An astronaut riding a horse on Mars, photorealistic',
      imageConfig: { imageSize: '2K', aspectRatio: '16:9' },
    }),
  },
)
const result = await response.json()
const image = result.candidates[0].content.parts[0].inlineData

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'provider': 'google',
        'model': 'gemini-3-pro-image',
        'prompt': 'An astronaut riding a horse on Mars, photorealistic',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '16:9'},
    },
)
result = response.json()
image = result['candidates'][0]['content']['parts'][0]['inlineData']

With reference images

Reference images work the same way on every endpoint. Use fileData when the image is already hosted, and inlineData when you have the bytes in memory.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://example.com/character.png",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "inlineData": {
          "data": "'"$(base64 -w0 character.png)"'",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

Asynchronous generation

For long-running or high-resolution requests, submit a task and poll for the result instead of holding a request open.

Create an async task

POST /v1/images/generation/async

Same request body as the synchronous endpoint. Returns 202 with a taskId immediately; generation runs in the background and the resulting images are persisted as hosted URLs.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/async" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": { "imageSize": "4K", "aspectRatio": "16:9" }
  }'

Response (202):

{
  "code": 0,
  "message": "",
  "data": { "taskId": "65f0...", "status": "pending" }
}

Get a task

GET /v1/images/generation/tasks/{taskId}

Poll for the status and result of a single task. status is one of pending, generating, success, or fail. On success, images holds the hosted result URLs.

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks/65f0abc..." \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "65f0abc...",
    "status": "success",
    "images": [{ "url": "https://.../0.png", "mimeType": "image/png" }],
    "createdAt": 1750000000000,
    "completedAt": 1750000020000
  }
}

List tasks

GET /v1/images/generation/tasks

List your image tasks, newest first.

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks?page=1&pageSize=20&status=success" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "taskId": "65f0...",
        "status": "success",
        "images": [],
        "createdAt": 1750000000000,
        "completedAt": 1750000020000
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

Estimate credits

POST /v1/images/generation/estimate-credits

Returns the credit cost for a given configuration and whether your account can afford it, without spending credits or calling the model. Accepts the same body as the generation endpoints; provider and prompt are optional here.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/estimate-credits" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "1:1"
    }
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      imageConfig: { imageSize: '2K', aspectRatio: '1:1' },
    }),
  },
)
const { data } = await response.json()
console.log(data.credits, data.canGenerate)

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'model': 'gpt-image-2',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '1:1'},
    },
)
data = response.json()['data']
print(data['credits'], data['canGenerate'])

Estimate response

Wrapped in the standard envelope. The data object:

{
  "code": 0,
  "message": "",
  "data": {
    "model": "gpt-image-2",
    "imageSize": "2K",
    "aspectRatio": "1:1",
    "credits": 6,
    "canGenerate": true,
    "requiresSubscription": false,
    "pricing": { "pricingVersion": "gpt-image-2-lite-fixed-2026-06-15", "mode": "fixed" },
    "warnings": []
  }
}

Free generations

API key calls draw on the same account-level free-quota (freeUsages) balance as the ListenHub and Labnana apps. You earn quota through sign-up, invites, and check-ins, then spend it through the API. Query the live balance via GET /v1/user/subscription and read its freeUsages map.

When the matching balance is greater than 0, a 1K or 2K request spends one free generation instead of credits. Once the balance hits 0, the same request falls back to normal credit billing.

gemini-3-pro-image is the only model whose free quota runs on a separate execution lane, with its own failure metadata to branch on — see Nano Banana → the relax lane.

Response formats

The synchronous endpoint returns the raw model output directly. A successful body contains the generated image as base64 data:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_ENCODED_IMAGE>"
            }
          }
        ]
      }
    }
  ]
}

Decode the data field from base64 to obtain the image file. The async path persists the image for you and returns hosted urls on the task object — no base64 decoding needed.

Error codes

Errors use the standard envelope with a non-zero code or, for the synchronous endpoint, the raw error body described in Free generations.

Both generation endpoints are rate limited per user and globally. Requests carrying base64 reference images (inlineData) are subject to a separate, tighter limit and may be throttled first at peak times. estimate-credits is not rate limited.

Related