Skip to content

2.5.0 — image families, URL inputs, account, training, video, commercial tools

Choose a tag to compare

@qmt qmt released this 11 Oct 08:49
· 15 commits to main since this release
05f693e

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: true on 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 at 1d, 168 hours at 1h)
    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_invoices and
    ideogram_api_keys list 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 of GET /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, Infinity turns 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); where request_id, user_id and timestamp travel is not stated by the specification.

  • ideogram_operations and 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) and ideogram_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_model is served raw. Support: curated 57 · raw
    6 · planned 64; tools/list: 23 tools.

  • A dataset created by ideogram_dataset_upload is 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.png pairs with its caption as red 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 carry details.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 (rawWriteFailures counted);
    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 or ideogram_api whose
    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.png is x.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 advertise inline_images; asked anyway, the answer says it
    has no effect); a long job comes back as a generation_id for ideogram_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_identifier and end_image / end_image_asset_identifier are alternatives; MiniMax takes at most 12
    references across images, videos and audio. duration says 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 price generate_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_identifier inputs of a later call. The spec-only video edit is served raw
    behind allow_undocumented. Support: curated 68 · raw 7 · planned 52; tools/list: 26 tools.

  • ideogram_generation lost its video input: 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's Asset: line is the whole identifier ({"asset_type": "RESPONSE", "asset_id": …}), ready for an
    *_asset_identifier input. ideogram_quote (and ideogram_api with dry_run) says when the dry run leaves
    generate_audio out of the price (measured: the same quote with and without it; Ideogram: about double). A video
    entry that carries a duration but no object_type is a video (the specification leaves the type optional).

  • get_asset_reference_usage (spec-only) is served by ideogram_api behind allow_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 — a FamilyToolSpec may name one
    operation: no model input, 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 tools ideogram_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_quote prices 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 utilities ideogram_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) and ideogram_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). The image /
    image_asset_identifier rule 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 through ideogram_api
    (allow_undocumented where 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's async kind 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 carry responseMedia (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's image_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 no wait_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. responseMedia knows video too.

  • ideogram_precise_edit (Ideogram 4.5: the image, an optional mask, up to four reference_images or
    reference_image_asset_identifiers, context_window), ideogram_remove_background and ideogram_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_files are sent as fonts — .ttf, .otf, .woff, .woff2 — and refused as images, and
    an image is refused as a font). Each is priced by ideogram_quote and collected by ideogram_generation like any
    other; the four were reachable through ideogram_api only 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_window needs the image as a file and "auto" needs a mask; remove object
    needs its source and its mask.

  • A layered payload in the lifecycle: a layerized_image / layerized_design.generation entry 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.

  • private is a field of every curated tool whose model takes it, and is sent as true unless the caller sets it:
    on remove background, replace background and the auto models an omitted private follows 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_api sends 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_images and reference_image_asset_identifiers are 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_files takes at most 5 (X5, X6, X9).

Changed

  • tools/list carries 16 tools; a definition shorter than its $ref is 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, private included; 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.mjs pins 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_image and
    get_images_by_collection_id were missing from the list).

  • scripts/spec-gen/: js-yaml 4.3.2 through an exact overrides entry — 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).