API reference · Ideogram
ideogram-ai/ideogram-v3/character
Integrate this model through SandBase's unified API, with production-ready schemas and examples.
Production endpoint
Send your first request
OpenAI-compatible endpoint with unified authentication and usage tracking.
POST
https://api.sandbase.ai/v1/runModel ID
ideogram-ai/ideogram-v3/character01
Input Schema
7 parameters · 1 required · 6 optional
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Required | The prompt to fill the masked part of the image. |
seed | integer | Optional | Seed for the random number generator |
images | string[] | Optional | A set of images to use as style references (maximum total size 10MB across all style references). The images should be in JPEG, PNG or WebP format |
aspect_ratio | string | Optional | The aspect ratio of the generated image. · Options: 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16 21:916:93:24:35:41:14:53:42:39:16 |
reference_masks | string[] | Optional | A set of masks to apply to the character references. Currently only 1 mask is supported, rest will be ignored. (maximum total size 10MB across all character references). The masks should be in JPEG, PNG or WebP format |
rendering_speed | string | Optional | The rendering speed to use. · Options: TURBO, BALANCED, QUALITY · Default: "BALANCED" TURBOBALANCEDQUALITY |
reference_images | string[] | Optional | A set of images to use as character references. Currently only 1 image is supported, rest will be ignored. (maximum total size 10MB across all character references). The images should be in JPEG, PNG or WebP format |
02
Output Schema
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the generation task |
status | string | Task status: pending, running, completed, failed, timeout |
model | string | Model used for the generation |
outputs | array | Array of output items |
outputs[].url | string | URL of the generated artifact |
outputs[].content_type | string | MIME type (e.g. image/png, video/mp4) |
error | object | null | Error details if failed, null on success |
error.type | string | Machine-readable error type code |
error.message | string | Human-readable error description |
Async Workflow
This model uses asynchronous execution. Submit a request and poll for the result.
- Submit — POST to /v1/run, receive an
id - Poll — GET /v1/run/{id} until status is
completed,failed, ortimeout - Retrieve — Read
outputsfrom the completed response
03
Code Examples
Ready-to-run snippets
const apiKey = process.env.SANDBASE_API_KEY;
const response = await fetch("https://api.sandbase.ai/v1/run", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "ideogram-ai/ideogram-v3/character",
"prompt": "Place the woman leisurely enjoying a cup of espresso while relaxing at a sunlit café table in Siena, Italy. The café setting showcases vintage wooden furniture with peeling white paint, aged brick flooring, and sun-bleached stone walls decorated with trailing ivy and vibrant potted geraniums that capture Siena's medieval character. Golden late-morning light streams through overhead, creating soft shadows that highlight the weathered architectural details. The composition appears slightly off-center, conveying the unguarded tranquility and personal intimacy of a peaceful moment savoring the Tuscan morning ambiance.",
"rendering_speed": "BALANCED",
"reference_images": [
"https://static.sandbase.ai/examples/ideogram-ai/ideogram-v3/character/input_reference_image_urls_0.png"
]
}),
});
if (!response.ok) throw new Error(await response.text());
let result = await response.json();
for (let attempt = 0; attempt < 120 && !["completed", "failed", "timeout"].includes(result.status); attempt++) {
await new Promise((resolve) => setTimeout(resolve, 2_000));
const poll = await fetch(`https://api.sandbase.ai/v1/run/${result.id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!poll.ok) throw new Error(await poll.text());
result = await poll.json();
}
if (result.status !== "completed") throw new Error(`Generation ended: ${result.status}`);
console.log(result);