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
| Field | Type | Required | Default | Range | Description |
|---|---|---|---|---|---|
| model | string | yes | — | see model table | Image model id from the catalog below. |
| prompt | string | yes | — | per-model | Text describing the image to generate. |
| size | string | optional | model default | WxH (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. |
| n | number | optional | 1 | 1 – 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_ratio | string | optional | derived from size | 1:1 / 16:9 / 9:16 / 4:3 / 3:4 | Used by Kontext Max instead of `size`. Other models derive aspect from `size` automatically. |
| image | string | edit-only | — | URL or base64 | Reference 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 ID | Price | Notes |
|---|---|---|
| bytedance/seedream-4.0 | $0.030 / image | Strong general-purpose. Accepts large sizes (3.7M–16.7M pixels). Up to 15 images per call. |
| bytedance/seedream-4.5 | $0.030 / image | Refresh of 4.0. Supports image-edit mode via the `image` field. |
| bytedance/seedream-5.0-lite | $0.035 / image | Newest Seedream. Smaller checkpoint, faster. Max area 10.4M pixels. |
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 family | Constraint | If exceeded |
|---|---|---|
| seedream-4.0 / 4.5 | Total area 3.69M – 16.78M pixels | Scaled up or down to fit the band; aspect preserved. |
| seedream-5.0-lite | Total area 3.69M – 10.40M pixels | Tighter than 4.x: large sizes clamped to 10.4M. |
Common errors
| Status | What it means | Fix |
|---|---|---|
| 400 | Invalid body: wrong size format, unsupported model, missing image for edit mode | Check the body fields above and the per-model size constraints. |
| 402 | Insufficient balance | Top up in the dashboard. Image calls deduct atomically before sending upstream. |
| 404 | Model not in catalog | Pick a model from the table above. |
| 429 | Account-level rate limit (60 req/min) | Slow down or contact us for a higher limit. |
| 502 | Upstream returned an unexpected response | Retry. If persistent, paste x-upstream-request-id in a support ticket. |
| 504 | Upstream took too long to generate (typically 60–150s budget) | Retry, or try a faster model (seedream-4.0 or seedream-4.5). |
Try it without code. The lets you pick any image model, type a prompt, choose an aspect ratio, and see the result inline.