Image generation API

Overview

The SeaWhale AI image generation API is fully compatible with the OpenAI SDK. Point baseURL at SeaWhale AI and client.images.generate works with no other code changes. Flux, Gemini, DALL·E and other leading image models are supported.

Quick start (OpenAI SDK)

TypeScript / Node.jsPython

typescript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.seawhaleai.com/v2',
})

const response = await client.images.generate({
  model: 'flux-2-pro',
  prompt: 'A cute kitten playing in the sunshine, photographic style, soft lighting',
  n: 1,
  size: '1024x1024',
})

console.log(response.data[0].url)

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.seawhaleai.com/v2",
)

response = client.images.generate(
    model="flux-2-pro",
    prompt="A cute kitten playing in the sunshine, photographic style, soft lighting",
    n=1,
    size="1024x1024",
)

print(response.data[0].url)

Endpoint

POST https://api.seawhaleai.com/v2/images/generations

Request format

Headers

Header	Type	Required	Description
Content-Type	string	Yes	Always `application/json`
Authorization	string	Yes	`Bearer YOUR_API_KEY`

Request parameters

Identical to the OpenAI images.generate parameters:

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	Model name, e.g. `"flux-2-pro"` or `"dall-e-3"`
`prompt`	string	Yes	—	Text description of the image, in any language
`n`	integer \| null	No	`1`	Number of images to generate; dall-e-3 supports only `1`
`size`	string \| null	No	`"1024x1024"`	Output dimensions, see the size table below
`quality`	string	No	`"standard"`	Image quality: `"standard"` or `"hd"` (dall-e-3 only)
`style`	string \| null	No	`"vivid"`	Style: `"vivid"` or `"natural"` (dall-e-3 only)
`user`	string	No	—	End-user identifier, used for monitoring and abuse detection

Supported sizes

Size	Aspect ratio	Best for
`256x256`	1:1	Small icons (dall-e-2)
`512x512`	1:1	Medium size (dall-e-2)
`1024x1024`	1:1	Square, general purpose
`1792x1024`	16:9	Widescreen, banners, video covers
`1024x1792`	9:16	Vertical, phone wallpapers, Stories

Code examples

Basic text-to-image

TypeScriptPythoncURL

typescript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.seawhaleai.com/v2',
})

const response = await client.images.generate({
  model: 'flux-2-pro',
  prompt: 'futuristic city skyline at sunset, cyberpunk style, neon lights',
  n: 1,
  size: '1792x1024',
})

const imageUrl = response.data[0].url
console.log('Generated image URL:', imageUrl)

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.seawhaleai.com/v2",
)

response = client.images.generate(
    model="flux-2-pro",
    prompt="futuristic city skyline at sunset, cyberpunk style, neon lights",
    n=1,
    size="1792x1024",
)

image_url = response.data[0].url
print(f"Generated image URL: {image_url}")

bash

curl https://api.seawhaleai.com/v2/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "futuristic city skyline at sunset, cyberpunk style, neon lights",
    "n": 1,
    "size": "1792x1024"
  }'

Getting a base64 image

TypeScriptPython

typescript

const response = await client.images.generate({
  model: 'flux-2-pro',
  prompt: 'A cute Shiba Inu, Ghibli-style illustration, warm tones',
  n: 1,
  size: '1024x1024',
})

const b64 = response.data[0].b64_json
// Display it in the browser
const imgSrc = `data:image/png;base64,${b64}`

python

import base64

response = client.images.generate(
    model="flux-2-pro",
    prompt="A cute Shiba Inu, Ghibli-style illustration, warm tones",
    n=1,
    size="1024x1024"
)

b64_data = response.data[0].b64_json
image_bytes = base64.b64decode(b64_data)

with open("output.png", "wb") as f:
    f.write(image_bytes)

print("Image saved to output.png")

Error handling

TypeScriptPython

typescript

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.seawhaleai.com/v2',
})

try {
  const response = await client.images.generate({
    model: 'flux-2-pro',
    prompt: 'A cute kitten',
    n: 1,
    size: '1024x1024',
  })
  console.log(response.data[0].url)
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    console.error('Status code:', error.status)
    console.error('Error message:', error.message)
  } else {
    throw error
  }
}

python

from openai import OpenAI, APIError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.seawhaleai.com/v2",
)

try:
    response = client.images.generate(
        model="flux-2-pro",
        prompt="A cute kitten",
        n=1,
        size="1024x1024",
    )
    print(response.data[0].url)
except APIError as e:
    print(f"Status code: {e.status_code}")
    print(f"Error message: {e.message}")

Response format

The response structure matches OpenAI images.generate exactly:

typescript

type ImagesResponse = {
  created: number // Unix timestamp
  data: Image[] // Generated images
}

type Image = {
  url?: string // Image URL
  b64_json?: string // Base64 image data
  revised_prompt?: string // Refined prompt (supported by some models)
}

Example responses

URL format (default)

json

{
  "created": 1713200000,
  "data": [
    {
      "url": "https://example.com/generated-image.png",
      "revised_prompt": "A cute kitten playing in sunlight, photography style, soft lighting, shallow depth of field"
    }
  ]
}

Base64 format

json

{
  "created": 1713200000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    }
  ]
}

Best practices

Writing effective prompts

Describe the subject, style, lighting and composition specifically:

✅ Better:
"An orange kitten sitting on a wooden windowsill, sunset glow in the background,
warm side lighting, cinematic depth of field, photographic style, 8K ultra HD"

❌ Worse:
"cat"

Add style keywords:

Style: "oil painting", "watercolor", "cyberpunk", "Ghibli animation"
Lighting: "cinematic lighting", "soft light", "dramatic shadows"
Perspective: "wide-angle lens", "macro photography", "bird's-eye view"

Choosing a size

Use case	Recommended size
Social media feed	`1024x1024`
Stories / Reels	`1024x1792`
Website banner / video cover	`1792x1024`
Icons / avatars	`1024x1024`

Image URLs expire

Generated image URLs are usually temporary, so download them to your own storage promptly:

typescript

async function downloadAndSave(url: string, path: string) {
  const res = await fetch(url)
  const buffer = await res.arrayBuffer()
  await fs.promises.writeFile(path, Buffer.from(buffer))
}

const response = await client.images.generate({
  model: 'flux-2-pro',
  prompt: '...',
  n: 1,
  size: '1024x1024',
})
await downloadAndSave(response.data[0].url!, 'output.png')

Supported models

See the model list for every supported image generation model and its details, including:

Model capabilities
Pricing
Supported parameters

Quick start — how to get an API key and configure the basics
Model list — browse all available image generation models
Authentication — how API authentication works
FAQ — answers to common questions

Support

If you have questions or need help, contact us:

Live support: visit the SeaWhale AI website
Documentation: read the full API reference

Image generation API ​

Overview ​

Quick start (OpenAI SDK) ​

Endpoint ​

Request format ​

Headers ​

Request parameters ​

Supported sizes ​

Code examples ​

Basic text-to-image ​

Getting a base64 image ​

Error handling ​

Response format ​

Example responses ​

URL format (default) ​

Base64 format ​

Best practices ​

Writing effective prompts ​

Choosing a size ​

Image URLs expire ​

Supported models ​

Related resources ​

Support ​

Image generation API

Overview

Quick start (OpenAI SDK)

Endpoint

Request format

Headers

Request parameters

Supported sizes

Code examples

Basic text-to-image

Getting a base64 image

Error handling

Response format

Example responses

URL format (default)

Base64 format

Best practices

Writing effective prompts

Choosing a size

Image URLs expire

Supported models

Related resources

Support