ideogram/ideogram-4-6
Ideogram 4.6, served direct from Ideogram.
Text-to-image up to 4096×4096, and editing: send source images (the first is the one edited, the others are references) and an optional mask.
Billed per image by `quality` and size (2K or 4K): from $0.008 to $0.20 without input images and $0.008 to $0.60 with them.
Submit and poll on `POST /v1/ideogram/generations`, or send it to the Jobs API (`POST /v2/jobs`, one image per job).
Ideogram 4.6 on this gateway: ideogram/ideogram-4-6 (this page) · ideogram/ideogram-4-6-precise-edit. Overview, demos and prices on sociaro.com.
| Slug | ideogram/ideogram-4-6 |
| Kind | image |
| Vendor | ideogram |
| Endpoint | POST /v1/ideogram/generations |
Charged per job from what the generator reports it rendered — your Logs show the exact figure for each one; see balance and billing.
Calling it
curl https://api.sociaro.com/v1/ideogram/generations \
-H "Authorization: Bearer $SOCIARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram/ideogram-4-6",
"input": {"prompt": "a paper boat on a rain-soaked street", "images": ["https://your-cdn.example.com/photo.png"]}
}'
# then poll the job id it returns:
curl https://api.sociaro.com/v1/ideogram/generations/JOB_ID \
-H "Authorization: Bearer $SOCIARO_API_KEY"Parameters
Ideogram 4.6 — text to image up to 4K, and image editing with references and a mask
| Field | Type | Required | Default | Values | What it does |
|---|---|---|---|---|---|
input.prompt | string | yes | — | text, up to 10,000 characters | What to draw, or the edit to make when source images are sent. Plain language, or a structured JSON prompt. |
input.magic_prompt | string | no | auto | auto · on · off | `auto` and `on` let the generator rewrite and expand a plain prompt; `off` keeps your wording. With `images` the generator always uses `auto`. |
input.images | string[] | no | — | 1–5 public https urls (3 with a mask) | Source images, JPEG, PNG or WEBP, up to 25 MB each. The first is the one edited; the rest are references. Present, the request is priced as an edit. Urls only: no base64. |
input.mask | string | no | — | a public https url | Limits the edit to part of the first source image. Black is edited, white is kept; it must be the same width and height as that image and hold both black and white. JPEG, PNG or WEBP, up to 25 MB. Needs `images`, and allows at most 3 of them. |
input.size | string | no | auto | auto · source · WIDTHxHEIGHT | `auto` gives about 2048×2048. `WIDTHxHEIGHT`: both sides multiples of 32, at most 4096×4096, aspect at most 6:1. `source` matches the first of `images` and needs them. Sets the price tier: an area up to 2048×2048 pixels is 2K, larger is 4K; `auto` is 2K and `source` is the first image's size. |
input.background | string | no | auto | auto · transparent · opaque | `transparent` returns images with an alpha channel; `opaque` forces a solid background. |
input.quality | string | no | medium | very_low · low · medium · high | Sets the price, with the size tier and whether source images are sent. `very_low` renders up to 2K and is always $0.008: with a `WIDTHxHEIGHT` larger than 2048×2048 pixels in area it is a `400`. |
input.seed | integer | no | random | 0–2147483647 | The same seed and prompt reproduce the same picture. |
input.num_images | integer | no | 1 | 1–8 | Images generated per request, each billed. Fixed at 1 on `/v2/jobs`. |
Anything not listed here is refused rather than ignored, so a typo fails loudly instead of quietly producing something else.
Worked example
curl https://api.sociaro.com/v1/ideogram/generations \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "ideogram/ideogram-4-6",
"input": { "prompt": "a paper boat on wet asphalt, rain, late light", "size": "4096x2048",
"quality": "low", "num_images": 2 } }'
curl https://api.sociaro.com/v1/ideogram/generations/{job_id} -H "Authorization: Bearer $SOCIARO_API_KEY"
# the same on the Jobs API
curl https://api.sociaro.com/v2/jobs \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: my-request-0003" \
-d '{ "model": "ideogram/ideogram-4-6",
"input": { "prompt": "a paper boat on wet asphalt, rain, late light", "quality": "medium" } }'Submit and poll. Send ideogram/ideogram-4-6 to POST /v1/ideogram/generations and poll
GET /v1/ideogram/generations/{job_id} until status is completed. The pictures are in media_urls
(media_url is the first). On /v1 the links are on our domain and valid for one hour. On the
Jobs API (POST /v2/jobs, poll GET /v2/jobs/{id}) the picture is outputs[0].url, a permanent link on
our CDN, and num_images is fixed at 1.
Files are urls. images and mask take public https urls; the gateway fetches them itself and sends them on.
A url it cannot fetch, a file over the size limit or a file that is not JPEG, PNG or WEBP is a 400 naming the
field. async and webhook_url are refused: use the callback options of the job.
2K or 4K. An image is 2K when its area is at most 2048×2048 pixels (4,194,304) and 4K above that. The area
decides, not the longer side: 2880×1440 and 3328×1248 are 2K, 2080×2048 is 4K. The size is the size you ask
for; auto, or leaving size out, is 2K, and source is the size of the first of images. very_low is always
2K; under source, at any other quality, an image that comes back larger than 2048×2048 pixels in area is billed at
4K. Under source, a first image whose width and height cannot be read from its own header is a 400 naming it.
How it is billed. Per image the generator produced, at the rate of quality and size. Every image it produced
is billed, including an image it withheld after its own safety check; a withheld image is not delivered, so a job
can be billed for more images than it returns, and a job whose images were all withheld ends failed and is
still billed, on /v1 and /v2 alike. A request the generator refuses, and a job that fails without producing images, is not billed.
| quality | without input images, 2K | without input images, 4K | with input images, 2K | with input images, 4K |
|---|---|---|---|---|
| very_low | $0.008 | 2K only | $0.008 | 2K only |
| low | $0.03 | $0.06 | $0.03 | $0.06 |
| medium | $0.06 | $0.12 | $0.06 | $0.20 |
| high | $0.10 | $0.20 | $0.22 | $0.60 |
Two 4096×2048 images at low without input images (4K): 2 × $0.06 = $0.12. The same at size auto: 2 × $0.03 =
$0.06.
Copyright check. Always on, set by the gateway: enable_copyright_detection is not a field you send (it
is refused as unknown). An image the check flags is withheld like an unsafe one: not delivered, still billed.
Errors. The generator's own reason comes back in error.message, and its code (reject_reason on a
refusal, failure_reason on a failed job) in error.provider_code.
How a job runs
Generation takes longer than a request should wait, so it goes in three moves: submit, then poll, then collect.
# 1. submit — the model id plus the fields above
curl -sS https://api.sociaro.com/v1/alibaba/generations \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "…", "prompt": "…" }'
# -> { "job_id": "<id>", "status": "submitted" }
# 2. poll every 3-5 s for images, 5-10 s for video
curl -sS https://api.sociaro.com/v1/alibaba/generations/<id> \
-H "Authorization: Bearer $SOCIARO_API_KEY"
# -> { "job_id": "…", "status": "processing" }
# -> { "job_id": "…", "status": "completed", "model": "…",
# "media_url": "https://api.sociaro.com/v1/media/<media_id>" }
# -> { "job_id": "…", "status": "failed", "model": "…", "error": { "code": …, "message": … } }
# 3. collect within the hour — the opaque id IS the credential, no header needed
curl -sSL "https://api.sociaro.com/v1/media/<media_id>" -o out.mp4
Use the job_id verbatim as the path segment when polling: the two names are the same value.
Which submit and poll URL this model uses is at the top of this page, under Calling it.
Reading the poll
status is one of processing · completed · failed. Only completed carries media_url,
only failed carries error.
Gate on status, never on the poll's HTTP code. A poll-time failure is HTTP 200 with
status: "failed" and an error object of { "code", "message" }, plus provider_code when the
generator supplied one — on every failure branch, including one where the result could not be
delivered. A submit-time rejection is different: it comes back as its own HTTP status with the
reason in the body.
code is ours and stable; message is the generator's. Match on code: it comes from a small
fixed set, and provider_failed still means what it always meant. A rejection of what you sent —
a size out of range, an unusable input — additionally sets code: "invalid_request", because that is
a different thing for your code to do. message now carries the generator's own sentence, and
provider_code its own code (OutputVideoSensitiveContentDetected.PolicyViolation,
IPInfringementSuspect), so a moderated generation, a copyright refusal and a broken renderer are
finally distinguishable. Treat provider_code as informational: the vendors change these strings
without telling us, so branch on ours.
message is variable text, capped at 400 characters. It used to be a single fixed
43-character sentence, so if you compare it by equality or keep it in a narrower column, that needs
changing — match on code, and on provider_code when you need the finer distinction.
Two things that text is not. It does not name the generator behind the model: the names of the
services and hosts that actually run your job are substituted out before you see it, so do not parse
it for one. What it does not hide is a name you already have — the halves of the model id you
called (alibaba, bytedance, wan, qwen, seedance, seedream, happyhorse) stay as written,
because blanking those would garble the message exactly where it is useful: Model
alibaba/wan-2-7-image not found has to survive intact. And the text can quote your own request
back: a moderation message often contains the fragment it objected to. That is why we do not write
it into our own logs, and why forwarding or storing a failed poll's message is your decision to
make rather than something to do by default.
Collecting the result
media_url points at our host, not the generator's. It is a capability: the opaque id is the
credential, so no Authorization header is needed and anyone holding the link can fetch it. It
expires within the hour — download rather than store the link.
Several images are not optional extras. An Alibaba image model asked for more than one picture
(n above 1) is charged for the number of pictures the generator reports making, and every link it
returns is delivered, never fewer than that number: media_urls lists
all of them in the generator's order (present on every image result, even a single one) and
media_url is the first. Each has its own link and its own expiry. If any one of them cannot be
delivered the job is reported failed and nothing is charged — unlike a still or a layer, an
image you paid for is never left out.
Rules the gateway adds
Two fields are ours and never reach the generator:
| Field | Notes |
|---|---|
model |
which model to run |
user |
your own end-user id. Recorded against this job's spend so you can attribute cost per end user, and stripped before the request leaves us, so the generator never sees it. Validated BEFORE the job is created, so a rejection is free: a string of at most 128 characters, no control characters, valid UTF-8. Omitting it, or sending null, is fine and simply records no end user |
An unknown field is always a 400. Most generators reject one themselves; some accept it,
ignore it, render something other than what you asked for and bill you — so we refuse it for you.
Either way you get 400 unknown field(s): [...] naming the offender, never a surprise render.
Ranges and enums are the generator's own and we do not re-validate most of them, so an
out-of-range value comes back as its rejection, in its wording and with its numbers. The one thing
we DO check ourselves is resolution, because an unsupported tier is silently ignored rather than
refused: you would ask for the higher tier, be handed a lower one, and be charged. The tiers on
this page are read from what the vendor prices, so they change when the vendor publishes one.
Authentication
Authorization: Bearer <your-api-key> on submit and on poll. The key must be valid AND granted
this model — 403 otherwise.
One deliberate exception on poll: a key that is over budget may still poll and collect a job it already submitted, so work you have already paid for is never stranded by a budget that ran out mid-generation. While the key is over budget the gateway cannot read its model list at all, so the per-model grant is not re-checked on those polls — a grant revoked after submit still collects that job. Ownership is always enforced: a job can only be polled by the key that created it, and submit is always refused in that state.