Media Models

Image Generation

POST /images/generations matches the OpenAI Images spec — the official openai SDKs work unchanged with just a base URL swap. Models are async upstream but the gateway polls internally and returns the result URLs in one response (typically 5–60 seconds depending on the model).

Quickstart

image.py
#60a5fa]">from openai import OpenAI

client = OpenAI(
    api_key=#60a5fa]">class="text-emerald-400">"tl-xxxxxxxxxxxxxxxxxxxxxxxx",
    base_url=#60a5fa]">class="text-emerald-400">"https://api.thalam.ai/v1",
)

response = client.images.generate(
    model=#60a5fa]">class="text-emerald-400">"bytedance/seedream-4.0",
    prompt=#60a5fa]">class="text-emerald-400">"A futuristic city skyline at sunset, cinematic lighting.",
    size=#60a5fa]">class="text-emerald-400">"2048x2048",
    n=1,
)

#60a5fa]">for image in response.data:
    #60a5fa]">print(image.url)
image.ts
#60a5fa]">import OpenAI from class="text-emerald-400">"openai";

#60a5fa]">const client = new OpenAI({
  apiKey: process.env.THALAM_KEY,
  baseURL: #60a5fa]">class="text-emerald-400">"https://api.thalam.ai/v1",
});

#60a5fa]">const response = await client.images.generate({
  model: #60a5fa]">class="text-emerald-400">"bytedance/seedream-4.0",
  prompt: #60a5fa]">class="text-emerald-400">"A futuristic city skyline at sunset, cinematic lighting.",
  size: #60a5fa]">class="text-emerald-400">"2048x2048",
  n: 1,
});

response.data.forEach((image) => console.log(image.url));
curl
curl https://api.thalam.ai/v1/images/generations \
  -H #60a5fa]">class="text-emerald-400">"Authorization: Bearer tl-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H #60a5fa]">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    #60a5fa]">class="text-emerald-400">"model": class="text-emerald-400">"bytedance/seedream-4.0",
    #60a5fa]">class="text-emerald-400">"prompt": class="text-emerald-400">"A futuristic city skyline at sunset, cinematic lighting.",
    #60a5fa]">class="text-emerald-400">"size": class="text-emerald-400">"2048x2048",
    #60a5fa]">class="text-emerald-400">"n": 1
  }'

Request body

FieldTypeRequiredDefaultRangeDescription
modelstringyes—see model tableImage model id from the catalog below.
promptstringyes—per-modelText describing the image to generate.
sizestringoptionalmodel defaultWxH (e.g. '1024x1024')Output dimensions. Constraints vary per model — see size limits below. The gateway clamps oversized requests automatically to keep the request in range.
nnumberoptional11 – 15 (model-dep)Number of images to generate in one call. Most models cap at 4–8; Seedream 4.x/5.x accepts up to 15.
aspect_ratiostringoptionalderived from size1:1 / 16:9 / 9:16 / 4:3 / 3:4Used by Kontext Max instead of `size`. Other models derive aspect from `size` automatically.
imagestringedit-only—URL or base64Reference image for edit/img2img modes (FLUX Kontext, Seedream 4.5/5.0-lite). Send the URL or a data: URL.

Not yet supported. response_format: "b64_json" — the gateway always returns presigned URLs to avoid the 5–10× latency and memory cost of inlining the bytes. Fetch the URL within ~24 hours to download the image.

Response

OpenAI-compatible JSON envelope with a data array of image objects. URLs are presigned and expire after ~24 hours — download what you need within that window.

response
{
  #60a5fa]">class="text-emerald-400">"created": 1736294400,
  #60a5fa]">class="text-emerald-400">"data": [
    { #60a5fa]">class="text-emerald-400">"url": class="text-emerald-400">"https://...storage.../output-1.png" },
    { #60a5fa]">class="text-emerald-400">"url": class="text-emerald-400">"https://...storage.../output-2.png" }
  ]
}

Available models

Model IDPriceNotes
zhipu/z-image-turbo$0.005 / imageCheapest in catalog. Fast. Great for prototyping. 256–1536 per dim.
zhipu/glm-image$0.014 / imageZhipu general image model. Each dim 1024–2048, must be a multiple of 32, total ≤ 4 megapixels.
bytedance/seedream-4.0$0.030 / imageStrong general-purpose. Accepts large sizes (3.7M–16.7M pixels). Up to 15 images per call.
bytedance/seedream-4.5$0.030 / imageRefresh of 4.0. Supports image-edit mode via the `image` field.
bytedance/seedream-5.0-lite$0.035 / imageNewest Seedream. Smaller checkpoint, faster. Max area 10.4M pixels.
black-forest-labs/flux-2-pro$0.030 / imagePhotorealism leader. Each dim 256–1536. Supports up to 3 reference images.
black-forest-labs/flux.1-kontext-max$0.072 / imageBest for image editing / inpainting. Uses `aspect_ratio` enum instead of `size`. Up to 4 reference images.
tencent/hunyuan-image-3$0.100 / imageStrong photorealism + multi-aspect support. Each dim 256–1536.

Size limits — quick reference

The gateway silently clamps oversized requests so customers don't see upstream validation errors. Useful to know what you'll actually get back:

Model familyConstraintIf exceeded
hunyuan-image-3, z-image-turboEach dim 256–1536Scaled down to ≤1536 preserving aspect ratio.
seedream-4.0 / 4.5Total area 3.69M – 16.78M pixelsScaled up or down to fit the band; aspect preserved.
seedream-5.0-liteTotal area 3.69M – 10.40M pixelsTighter than 4.x — large sizes clamped to 10.4M.
glm-imageEach dim 1024–2048, multiple of 32Passed through; non-multiples of 32 may return upstream 400.
flux-2-proEach dim 256–1536Passed through; over-range returns upstream 400.
flux.1-kontext-maxUses aspect_ratio enum, not sizesize auto-converted to nearest supported ratio (1:1 / 16:9 / 9:16 / 4:3 / 3:4).

Common errors

StatusWhat it meansFix
400Invalid body — wrong size format, unsupported model, missing image for edit modeCheck the body fields above and the per-model size constraints.
402Insufficient balanceTop up in the dashboard. Image calls deduct atomically before sending upstream.
404Model not in catalogPick a model from the table above.
429Account-level rate limit (60 req/min)Slow down or contact us for a higher limit.
502Upstream returned an unexpected responseRetry. If persistent, paste x-upstream-request-id in a support ticket.
504Upstream took too long to generate (typically 60–150s budget)Retry, or try a faster model (z-image-turbo, glm-image).

Try it without code. The lets you pick any image model, type a prompt, choose an aspect ratio, and see the result inline.