Repository navigation
2.5.0 — image families, URL inputs, account, training, video, commercial tools
One release for steps 1–5 of docs/DESIGN-ideogram-v2.md: the paragraphs below state each step's counts as they stood after that step; the release ends at 38 tools (tools/list 131 396 bytes, budget 136 KB), support curated 80 · raw 47 · planned 0 · unsupported 73, 178 tests. Nothing a 2.0.0 client used is removed (the video input of ideogram_generation existed only inside this series).
Step 1 of docs/DESIGN-ideogram-v2.md: every image family of Ideogram's documentation index has its own tool.
Step 2: the account — usage and spend, invoices, API keys — and the webhook signature helper.
Step 3: custom-model training — datasets, their assets, the training of an Ideogram 4.0 or 3.0 model, the models.
Step 4: video — from a prompt, from an image, from references.
Step 5: the commercial tools and the v1 utilities, each one operation; nothing of the specification is planned any more.
Added
-
A file field (image, mask, reference and style images, fonts) takes a public
https://URL beside a local path, on
every tool (the family tools,ideogram_quote,ideogram_api): fetched one after another under the field's own
limit and the room the request cap leaves, as a type the field takes, from a public host only — no IP literal, no
local name, no private / loopback / link-local / carrier / site-local / mapped / translated address after
resolution, no redirect followed, never an empty body — inside the call's budget, over a connection pinned to the
very address the lookup answered (a DNS rebinding reaches nothing), local files read before any fetch, every
failure named with the URL and its cause; the threat model is section 9b of the design note. -
inline_images: trueon every tool that saves images (the family tools,ideogram_generation,ideogram_api):
each saved image under 3.75 MB (the model APIs behind the clients take 5 MiB of base64 per image), up to 10 MB per
result, is also returned as MCP image content with its media type normalized, for a client without access to this
machine's files; the others are named with their size and stay by path. Off by default. -
ideogram_usage: the organization's billed API usage as Ideogram reports it (GET /v2/account/usage: dense time
buckets of line items — product, endpoint, cost, billed units, the redacted API key, the source), the last 7 days
by day (24 hours by hour) unless told otherwise, a range over the API's span (92 days at1d, 168 hours at1h)
refused before asking, summed per product, unit and currency as decimal strings (never floats; an amount the sums
cannot read is counted and listed, not summed — an unreadable quantity leaves the cost in), the buckets written
exactly as received to a JSON file in the output directory (named by the whole query, owner-readable: the line items
carry emails and key prefixes) and printed too when under 64 KB: the shape ai-cost reads; the end of the range is
always sent, so the span the tool checked is the span the API sees; every account answer — the invoices, the API
keys, one off its specification (reported as such, never as a success) — is written to an owner-readable file the
same way and shown inline under 64 KB.ideogram_invoicesand
ideogram_api_keyslist what their endpoints return as received. All three need an organization-admin key: a 404
is said as that, with Ideogram's words. Reads only, never billed. -
verifyWebhook(dist/webhooks.js): the canonical message Ideogram signs
(request_id\nuser_id\ntimestamp\nsha256_hex(body)) checked against the JWKS ofGET /v1/.well-known/jwks.json
with Ed25519, the header's key first, a rotated key still accepted, the signature as base64, base64url or hex; a
replay refused by the timestamp (300 s by default,Infinityturns it off; the signature alone never expires); a
missing header is null, never a throw. A helper for the receiver: this server receives no webhook itself (a stdio process has no public
URL); whererequest_id,user_idandtimestamptravel is not stated by the specification. -
ideogram_operationsand the API reference list an operation's path and query parameters. -
ideogram_datasets(the list, searched by name, or one dataset with its files, captions and the models trained
from it),ideogram_dataset_upload(images, .txt caption sidecars and .zip archives — local paths or public https
URLs — into an existing dataset or a new one created from a name; what was accepted and what failed, with the
reason),ideogram_train(an Ideogram 4.0 or 3.0 model from a dataset of 15 to 100 images; any hyperparameter
routes to the advanced operation, each checked by its own schema; a field the model's training does not take is
refused by name) andideogram_models(the list by scope and status, or one model with its training runs): the
v1 endpoints the index keeps for training, curated.train_dataset_modelis served raw. Support: curated 57 · raw
6 · planned 64; tools/list: 23 tools. -
A dataset created by
ideogram_dataset_uploadis named first in every answer that follows (an upload error, a
200 off the schema, a file that cannot be written), so a retry uploads into it instead of making another; a create
answered off its schema says a dataset MAY exist. A URL's last segment is percent-decoded before it names the part
(red%20door.pngpairs with its caption asred door.png). every call with a side effect (create a dataset, upload assets, start a
training) has one typed outcome (sendOperation): refused, not sent, unknown, or the answer — a refused or never-sent
upload says "Nothing was uploaded", an unknown one "the assets MAY be in the dataset", an unknown train "a training
MAY have started and will be billed"; the client's status-0 errors carrydetails.sent(false when the budget ended
or the connection was refused before anything left this machine). The raw answer's file is best-effort: a directory
that cannot be written shows the answer inline and never turns a success into an error (rawWriteFailurescounted);
a LISTING whose answer is neither written nor small enough to print is an error (the data is the listing). The same
typed decision reaches every surface that sends a request with a side effect: a family tool orideogram_apiwhose
non-GET request fails after it left (a 5xx, a cut connection) says the operation MAY have run and be billed. A
decoded URL segment is cut at its last slash or backslash before it names a part (..%2F..%2Fx.pngisx.png). -
ideogram_video_text,ideogram_video_image,ideogram_video_reference: the three video families on the family
mechanism (Seedance 2.5 by default, Seedance 2, Kling 3 Standard, MiniMax H3; each model its own fields), async
only — a finished video is saved as mp4 (under its own 512 MiB download cap) with its measured length, resolution
and size, never returned inline (the video tools do not advertiseinline_images; asked anyway, the answer says it
has no effect); a long job comes back as a generation_id forideogram_generation. Audio references
(reference_audios) are sent as MP3 or WAV — the one field-type rule, anchored to the specification; a start and
an end image as parts or assets. The video families show their own sentences for the fields they share with the
image families (a resolution is a tier and goes with the aspect ratio; references are not an edit's) through one
lookup,fieldTextsFor. Rules anchored to the specification's prose: a reference-to-video model (MiniMax included)
needs a reference image or video;reference_images/reference_image_asset_identifiers,image/
image_asset_identifierandend_image/end_image_asset_identifierare alternatives; MiniMax takes at most 12
references across images, videos and audio.durationsays what an omitted value costs: Kling and MiniMax make
5 s, Seedance picks the length and is QUOTED at its maximum (measured 2026-10-11: seedance-2-5 omitted and 30 s
6.93 USD, 4 s 0.924, 10 s 2.31 at 720p; the dry run does not pricegenerate_audio;docs/PRICES-2026-10-11.md
quotes every video model at its minimum duration — Kling 3 s 0.252, Seedance 2 4 s 0.64). A saved image's line names
its Ideogram asset id, for the*_asset_identifierinputs of a later call. The spec-only video edit is served raw
behindallow_undocumented. Support: curated 68 · raw 7 · planned 52; tools/list: 26 tools. -
ideogram_generationlost itsvideoinput: the poll gaps within a 50 s wait (2, 3, 4.5, 6.75, 10.1, 15.2 s)
never reach either cap, so the knob had no effect; one cap for images and video. An empty result list says "no
image or video". A download the budget cuts names the re-collect path for videos as for images (one download loop). -
A download is checked against the kind its result promised: a video link that answers an image (a placeholder behind
a 200) is "Not saved: Expected a video", never counted as a saved video; an image link that answers a video likewise.
A saved image'sAsset:line is the whole identifier ({"asset_type": "RESPONSE", "asset_id": …}), ready for an
*_asset_identifierinput.ideogram_quote(andideogram_apiwithdry_run) says when the dry run leaves
generate_audioout of the price (measured: the same quote with and without it; Ideogram: about double). A video
entry that carries adurationbut noobject_typeis a video (the specification leaves the type optional). -
get_asset_reference_usage(spec-only) is served byideogram_apibehindallow_undocumented: a spec-only
operation of a curated family is raw, as the undocumented reframe models are. Support: curated 47 · raw 5 ·
planned 75. tools/list: 19 tools. -
Twelve single-operation tools (
src/tools/commercial.ts) on the family mechanism — aFamilyToolSpecmay name one
operation: nomodelinput, the operation's own fields, the same checks (schema, the shared rules,private
defaulting to true), the same request and result shaping. The documented commercial toolsideogram_ad_localizer,
ideogram_ad_resizer,ideogram_ad_variations,ideogram_colorways,ideogram_ghost_mannequin,
ideogram_material_swap,ideogram_model_pose_variants,ideogram_sketch_to_render(generations: accepted, waited
for, saved;ideogram_quoteprices the five that offer a dry run — measured 2026-10-11: ad resizer 0.1025 USD,
colorways 0.0717, material swap 0.0798; ad localizer and ghost mannequin answered "not available to this account"
on the test key), and the v1 utilitiesideogram_magic_prompt(the JSON prompt printed),ideogram_layerize_logos
(the base image saved, the detected layers listed with the reference each matched),ideogram_provenance(the
record printed) andideogram_snap_mask(the operation answers the mask as image/png: saved as any image is, under
the image cap and types —callToFile; a 5xx says the request MAY have run, never resent). Theimage/
image_asset_identifierrule reaches colorways and material swap (their prose: "Provide exactly one of").
Support: curated 80 · raw 47 · planned 0 · unsupported 73 — a v1-only operation of a curated family (the v1 model
variants, the webhook JWKS) and every spec-only or customer-specific tool and workflow run throughideogram_api
(allow_undocumentedwhere unlisted). tools/list: 38 tools, 132 254 bytes (the budget is 136 KB from this step;
the twelve tools with their field sentences cost 34 KB). An operation'sasynckind is read from its answer: a
200 that is a generation id with at most the job's own facts (time, status, seed, the size a reframe will make) is a
job; one that NAMES a generation beside facts of its own (provenance verify) is an answer, never polled — the kinds
of every exposable operation are pinned by a test. The facts carryresponseMedia(json · image · none). The tool
family shows its own sentences for the shared fields (aspect ratios with a colon, three quality tiers, logo
references); the rules anchored to its prose: masks / mask_asset_identifiers, materials / material_asset_identifiers
and garment_images / garment_asset_identifiers are alternatives, colors are paired with the masks, materials are one
or one per mask, at most 10 logo references; pose variants, sketch to render and ghost mannequin need their source
(the one source rule, named per operation). A single-operation tool describes a quote only where the operation
offers a dry run; magic prompt says the aspect ratio the model picked; logo layers are listed as layers; the snap
mask answer can be returned inline and takes no wait; a file answer whose write fails is "the operation ran and
answered; the file is lost here", never "may have run"; the file answer goes through call()'s send loop (a 429 is
retried as everywhere). The rules the raw-served operations state in their prose are enforced before any request:
exactly one of masks / mask_asset_identifiers and of materials / material_asset_identifiers (both AND neither
refused), the person and the garments of virtual try-on, exactly one of text_prompt / json_prompt on the six v1
Ideogram 4 generations, image / image_asset_identifier on the text layerizer, at most 15 garment photos on ghost
mannequin; the one source rule names model swap's and precise masked edit's source and the v1 edit'simage_urls,
and says only the fields the operation has (snap mask takes no asset). A tool may carry its own field sentences
(FamilyToolSpec.fieldTexts: magic prompt's aspect ratios take an x, snap mask's image takes no asset); a tool whose
operation is no job (magic prompt, provenance, logos, snap mask) takes nowait_s; snap mask's answer is said as
what it is (white = the object: as is for remove object, whose mask takes white as the region to remove, inverted for
inpaint, whose mask takes black). A 2xx that is no file of the kind, or over the cap, keeps the save's own typed
error ("the operation ran and answered, with no file this server keeps"); anything else — a failed write, a cut
connection, the budget's end mid-body — is a lost answer ("sending it again runs it again"). The
body probe reads its optional top-level fields as unknown, so a body of another shape is never turned into a
record.responseMediaknowsvideotoo. -
ideogram_precise_edit(Ideogram 4.5: the image, an optional mask, up to fourreference_imagesor
reference_image_asset_identifiers,context_window),ideogram_remove_backgroundandideogram_remove_object
(ideogram-1),ideogram_layerize(Ideogram 3.0: the text-free base image is saved, the detected text blocks are
returned as JSON;font_candidate_filesare sent as fonts — .ttf, .otf, .woff, .woff2 — and refused as images, and
an image is refused as a font). Each is priced byideogram_quoteand collected byideogram_generationlike any
other; the four were reachable throughideogram_apionly in 2.0.0. -
The rules the specification states in prose for these operations, refused before any request (
src/spec/overlay.ts,
each anchored to its phrase): references by reference need the edited image by reference and no mask; a mask leaves
room for three reference images;context_windowneeds the image as a file and"auto"needs a mask; remove object
needs its source and its mask. -
A
layeredpayload in the lifecycle: alayerized_image/layerized_design.generationentry of a generation is
shown as its base image (saved, or withheld by the safety check), the design's own link and editable page when the
API gives them, and its text blocks — never as a raw record. -
privateis a field of every curated tool whose model takes it, and is sent astrueunless the caller sets it:
on remove background, replace background and theautomodels an omittedprivatefollows the plan's setting,
public when the plan has none (the other operations default to private) — a server on an API key never publishes to
Ideogram's public feed unless asked.ideogram_apisends what the caller gave, as before. (Opus cross-review X1.) -
A curated tool refuses a call without a source image (image, images or an asset identifier; every family but
generate) before the schema and before any request, and checks the body against the schema of the format it is
sent in — a call without a file goes as JSON, whose schema may require what the multipart one leaves optional (X3, X4). -
Three more rules from the prose:
reference_imagesandreference_image_asset_identifiersare alternatives (the
files would be ignored);context_window's explicit region is four whole numbers, max above min, each side at least
256 px, aspect ratio within 1:6 and 6:1, at most 4 194 304 pixels;font_candidate_filestakes at most 5 (X5, X6, X9).
Changed
-
tools/list carries 16 tools; a definition shorter than its
$refis inlined (lossless, 1.3 KB; an inlined
definition is walked again and a definition is dropped only when nothing refers to it any more), and the advertised
schema budget is 80 KB measured (73 582 bytes over a real session on 2026-10-10,privateincluded; the 64 KB of
2.0.0 was the estimate before step 1 —test/budget.test.mjs, design note section 5). -
Verified on the live API on 2026-10-10 (0.07 USD): a precise edit (4.5,
very_low) and a remove background run
through acceptance, poll and download; the remove-background result is listed as an image without prompt or seed
and saved like any image (test/tools.test.mjspins the shape). -
ideogram_api's refusal of a planned operation names "this release", not a version. -
The plan's order after step 2 (design note section 8, operator decision 2026-10-10): custom-model training (v1)
before video, the commercial tools last; step 1's second change (not this one) brings inline image content and URL
input, opt-in, for clients without file access. -
docs/COMPETITION-2026-10-01.md: the official MCP page names 12 tools (generate_imageand
get_images_by_collection_idwere missing from the list). -
scripts/spec-gen/: js-yaml 4.3.2 through an exactoverridesentry — the nested 4.2.0 openapi-ts' ref-parser pinned
carried GHSA-52cp-r559-cp3m, GHSA-5p4m-2wfm-xmqj and GHSA-2883-xcg3-v3hh (three high Dependabot alerts at the 2.0.0
release); the lockfile regenerated under the override (npm ls js-yaml: one 4.3.2); CI audits that lockfile (#38).