Image Generation

POST/v1/run

Generate images using AI models like FLUX, Stable Diffusion, DALL-E, and more.

For an image model that runs asynchronously, you may either set webhook_url on one request or register an organization Model Webhook. Synchronous calls and LLM calls do not support task callbacks; if they contain this field, SandBase ignores it and schedules no callback. See Webhooks.

Parameters

Parameter	Type	Required	Description
model	string	✅	Model name (e.g. flux/schnell, dall-e-3)
prompt	string	✅	Text description of the image
width	integer	❌	Image width in pixels
height	integer	❌	Image height in pixels
num_images	integer	❌	Number of images to generate (default: 1)
mode	string	❌	Set to async only when the selected model supports asynchronous execution
webhook_url	string	❌	Public HTTPS callback URL for this async task only

Example

response = client.post("/v1/run", json={
    "model": "flux/schnell",
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "width": 1024,
    "height": 1024
})
print(response.json()["outputs"][0]["url"])

Per-task callback (async only)

Set webhook_url when the selected image model resolves to asynchronous execution:

response = client.post("/v1/run", json={
    "model": "example/async-image-model",
    "mode": "async",
    "prompt": "A futuristic city at sunset, cyberpunk style",
    "webhook_url": "https://hooks.example.com/sandbase/task?token=opaque-token"
})
generation_id = response.json()["id"]

SandBase sends the completed, failed, or timeout event to that URL with X-Event-ID. Delivery is at-least-once, so deduplicate by that ID and return 2xx quickly. The URL must be public HTTPS. When webhook_url is present, it is the only callback target for this task and registered organization Model Webhooks are skipped; failures retry the same task URL without fallback. Per-task callbacks do not include X-Signature; omit webhook_url and use an organization Model Webhook when HMAC verification is required.

Available Models

Model	Provider	Price per image
flux/schnell	Black Forest Labs	$0.003
flux/dev	Black Forest Labs	$0.025
dall-e-3	OpenAI	$0.04–$0.12
stable-diffusion-3	Stability AI	$0.03
ideogram/v2	Ideogram	$0.05

→ Browse all image models