Images

Generate images from text prompts. Supports multiple providers (DALL-E 3, Stable Diffusion, Imagen) through a single endpoint.

Endpoint: POST /v1/inference/images/generate

Basic request#

bash
curl -X POST https://scaigrid.scailabs.ai/v1/inference/images/generate \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "A cozy reading nook with warm lighting, studio ghibli style",
    "size": "1024x1024",
    "quality": "standard",
    "n": 1
  }'

python
import httpx, os

resp = httpx.post(
    "https://scaigrid.scailabs.ai/v1/inference/images/generate",
    headers={"Authorization": f"Bearer {os.environ['SCAIGRID_API_KEY']}"},
    json={
        "model": "openai/dall-e-3",
        "prompt": "A cozy reading nook with warm lighting, studio ghibli style",
        "size": "1024x1024",
        "quality": "standard",
        "n": 1,
    },
    timeout=120,
)
data = resp.json()["data"]
print(data["data"][0]["url"])

typescript
const resp = await fetch("https://scaigrid.scailabs.ai/v1/inference/images/generate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCAIGRID_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/dall-e-3",
    prompt: "A cozy reading nook with warm lighting, studio ghibli style",
    size: "1024x1024",
    quality: "standard",
    n: 1,
  }),
});
const { data } = await resp.json();
console.log(data.data[0].url);

Parameters#

Field	Type	Notes
`model`	string (required)	Image model slug
`prompt`	string (required)	Text description
`n`	integer	Number of images to generate (typically 1–10)
`size`	string	`"1024x1024"`, `"1792x1024"`, `"1024x1792"`, model-dependent
`quality`	string	`"standard"` or `"hd"` for DALL-E 3
`style`	string	`"vivid"` or `"natural"` for DALL-E 3
`response_format`	string	`"url"` (default, short-lived proxy URL) or `"b64_json"` (inline base64)
`metadata`	object	Passed through to the provider

Response shape#

json
{
  "status": "ok",
  "data": {
    "created": 1713888000,
    "data": [
      {
        "url": "https://scaigrid.scailabs.ai/v1/media/tok_abc123",
        "b64_json": null,
        "revised_prompt": "A cozy reading nook..."
      }
    ]
  }
}

When response_format is "url", the URL points at ScaiGrid's media proxy — the image is stored in our object storage and served through a short-lived token. URLs expire after 1 hour by default; download the image or re-encode it if you need longer retention.

When response_format is "b64_json", the response contains inline base64 instead. Useful when your client can't make a second HTTP request to fetch the image.

Downloading and saving#

python
import httpx, base64

# If URL format
img_resp = httpx.get(data["data"][0]["url"])
with open("output.png", "wb") as f:
    f.write(img_resp.content)

# If b64_json format
b64 = data["data"][0]["b64_json"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

typescript
import { writeFileSync } from "node:fs";

const url = data.data[0].url;
const img = await fetch(url);
writeFileSync("output.png", Buffer.from(await img.arrayBuffer()));

Available image models#

bash
curl "https://scaigrid.scailabs.ai/v1/models?modality=image" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"

Common options:

Model	Size options	Notes
`openai/dall-e-3`	1024x1024, 1792x1024, 1024x1792	High quality, style/quality parameters
`openai/dall-e-2`	256x256, 512x512, 1024x1024	Older, cheaper
`stability/sd-xl`	1024x1024	Self-hosted via ScaiInfer

Availability depends on which providers your tenant has configured.

Revised prompts#

DALL-E 3 rewrites prompts for better results. The rewritten version comes back in revised_prompt:

python
data = resp.json()["data"]
item = data["data"][0]
print("You asked for:", "A cozy reading nook...")
print("Model generated:", item["revised_prompt"])

This is useful for debugging ("why did I get a cartoon when I asked for a photo?"). You can disable prompt rewriting by prefixing your prompt with I NEED to test how the tool works with extremely simple prompts. DO NOT add any detail, just use it AS-IS: — this is OpenAI's documented escape hatch.

Error cases#

Code	Meaning
`VALIDATION_ERROR`	Missing prompt or invalid size
`MODEL_ACCESS_DENIED`	Image model not enabled for your tenant
`BACKEND_ERROR`	Safety filter triggered, or upstream rejected the prompt
`BUDGET_EXCEEDED`	Image generation often has its own budget cap (expensive)

What's next#

Audio — speech synthesis and transcription.
Chat Completions — send generated images back to a vision model.
OpenAI Compatibility — /oai/v1/images/generations works identically.