Image Generation

Generate AI images from text prompts via API, with optional reference images provided as URLs or base64-encoded inline data.

Generate Image

POST /v1/images/generation

Generate an AI image from a text prompt. Optionally supply reference images to guide the style or content of the output. The response streams the raw model output (JSON containing base64 image data).

Basic Generation

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",
    "prompt": "A serene mountain landscape at sunset with a reflective lake",
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }'

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',
    prompt: 'A serene mountain landscape at sunset with a reflective lake',
    imageConfig: {
      aspectRatio: '16:9',
      imageSize: '2K',
    },
  }),
});
const data = await response.json();
// data.candidates[0].content.parts[0].inlineData contains the generated image

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',
        'prompt': 'A serene mountain landscape at sunset with a reflective lake',
        'imageConfig': {
            'aspectRatio': '16:9',
            'imageSize': '2K',
        },
    }
)
data = response.json()
# data['candidates'][0]['content']['parts'][0]['inlineData'] contains the generated image

Generation with Reference Images

Supply reference images to guide the output. Each reference image can be provided as either a URL (fileData) or base64-encoded inline data (inlineData). You can mix both formats in a single request.

Using Image URLs

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",
    "prompt": "Transform this scene into a watercolor painting style",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://example.com/my-photo.jpg",
          "mimeType": "image/jpeg"
        }
      }
    ],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "2K"
    }
  }'

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',
    prompt: 'Transform this scene into a watercolor painting style',
    referenceImages: [
      {
        fileData: {
          fileUri: 'https://example.com/my-photo.jpg',
          mimeType: 'image/jpeg',
        },
      },
    ],
    imageConfig: {
      aspectRatio: '1:1',
      imageSize: '2K',
    },
  }),
});
const data = await response.json();

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',
        'prompt': 'Transform this scene into a watercolor painting style',
        'referenceImages': [
            {
                'fileData': {
                    'fileUri': 'https://example.com/my-photo.jpg',
                    'mimeType': 'image/jpeg',
                }
            }
        ],
        'imageConfig': {
            'aspectRatio': '1:1',
            'imageSize': '2K',
        },
    }
)
data = response.json()

Using Base64 Inline Data

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",
    "prompt": "Create a cartoon version of this portrait",
    "referenceImages": [
      {
        "inlineData": {
          "data": "<BASE64_ENCODED_IMAGE>",
          "mimeType": "image/png"
        }
      }
    ]
  }'

import { readFileSync } from 'fs';

const imageBase64 = readFileSync('reference.png').toString('base64');

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',
    prompt: 'Create a cartoon version of this portrait',
    referenceImages: [
      {
        inlineData: {
          data: imageBase64,
          mimeType: 'image/png',
        },
      },
    ],
  }),
});
const data = await response.json();

import os
import base64
import requests

with open('reference.png', 'rb') as f:
    image_base64 = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'provider': 'google',
        'prompt': 'Create a cartoon version of this portrait',
        'referenceImages': [
            {
                'inlineData': {
                    'data': image_base64,
                    'mimeType': 'image/png',
                }
            }
        ],
    }
)
data = response.json()

Request Parameters

Field	Type	Required	Description
`provider`	string	Yes	Model provider. Currently only `google` is supported
`model`	string	No	Model name. `gemini-3-pro-image-preview` (default) or `gemini-3.1-flash-image-preview`
`prompt`	string	Yes	Text description of the image to generate
`referenceImages`	array	No	Reference images to guide generation, max 14 items
`referenceImages[].fileData`	object	No	Reference image as a URL
`referenceImages[].fileData.fileUri`	string	Yes	Image URL (`http`, `https`, or `gs` scheme)
`referenceImages[].fileData.mimeType`	string	Yes	MIME type: `image/png`, `image/jpeg`, or `image/webp`
`referenceImages[].inlineData`	object	No	Reference image as base64-encoded data
`referenceImages[].inlineData.data`	string	Yes	Base64-encoded image data
`referenceImages[].inlineData.mimeType`	string	Yes	MIME type: `image/png`, `image/jpeg`, or `image/webp`
`imageConfig`	object	No	Image output configuration
`imageConfig.imageSize`	string	No	Output resolution: `1K`, `2K` (default), or `4K`
`imageConfig.aspectRatio`	string	No	Aspect ratio (see table below)

Each item in referenceImages must contain exactly one of fileData or inlineData, not both.

Supported Aspect Ratios

Ratio	Description
`1:1`	Square
`2:3`	Portrait
`3:2`	Landscape
`3:4`	Portrait
`4:3`	Landscape
`9:16`	Vertical / mobile
`16:9`	Widescreen
`21:9`	Ultra-wide

The gemini-3.1-flash-image-preview model supports additional aspect ratios (1:4, 4:1, 1:8, 8:1) that are not available with the default gemini-3-pro-image-preview model.

Model Comparison

Model	Strengths	Notes
`gemini-3-pro-image-preview`	Higher quality, more detailed output	Default model
`gemini-3.1-flash-image-preview`	Faster generation, supports extra aspect ratios	Good for iterative workflows

Response

The response streams the raw model output as JSON. A successful response 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.

Rate Limiting and Reference Image Mode

Standard text-to-image requests are subject to per-user and global rate limits.

Reference image mode (referenceImages with inlineData) is subject to additional server-side resource constraints. During peak usage periods, requests may be throttled more aggressively. If you receive a 429 Too Many Requests response, wait a short period before retrying. We recommend implementing exponential backoff in your client.

Error Codes

HTTP Status	Meaning
`400`	Invalid request parameters (e.g., unsupported aspect ratio for the selected model)
`402`	Insufficient credits
`429`	Rate limit exceeded — retry after a short wait
`500`	Image generation failed — retry the request

On this page