Skip to main content
Glama
deenesjakoruzh
qmediat

ideogram-mcp

by qmediat
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

@qmediat.io/ideogram-mcp

MCP server for the Ideogram platform through its v2 API: every image and video model Ideogram sells through one API key — Ideogram 4.5, 4.0, 3.0, 2a and 2.0, GPT Image, Nano Banana, P-Image, Z-Image, the Topaz upscalers; Seedance 2.5 and 2, Kling 3, MiniMax H3 for video — for generate, precise edit, inpaint, remix, reframe, replace background, remove background, remove object, upscale, describe, layerize and video (from a prompt, an image or references), the commercial tools (ad localizer, resizer and variations, colorways, ghost mannequin, material swap, model pose variants, sketch to render), the utilities (magic prompt, layerize logos, provenance, snap mask), plus the account's usage, invoices and keys and custom-model training, from Claude Code, Claude Desktop or any MCP client over stdio. Every call can be priced first (the API's own dry run), long jobs are returned by id and collected later, and any other operation the release serves is one validated raw call away. Built from Ideogram's OpenAPI specification (ADR-0001).

npm version license TypeScript node

Why this server?

  • The platform, not one model — model on every tool, with each model's own fields (a field the model does not take is refused, naming the models that do). The model lists and fields come from Ideogram's specification, so a new model is a reviewed snapshot update, not a rewrite

  • Price before you pay — ideogram_quote asks the API what exactly this call would cost (USD and credits; nothing generated or billed)

  • Private by default — every curated tool whose model takes private sends it as true unless you set it (on remove background, replace background and the auto models the API's own default is your plan's setting); a model without the field (reframe with Ideogram 3.0, remove object) follows the API's own behaviour, and ideogram_api sends what you give it

  • Never billed twice — a job is returned the moment Ideogram accepts it; the tool waits up to wait_s and otherwise hands back the generation_id for ideogram_generation. A request is resent only when it never left the machine or got a 429

  • Everything else, validated — ideogram_operations lists what the API offers; ideogram_api calls any served operation by id, checked against its own schema first

  • Guarded I/O — per-operation upload limits checked before any file is read, streamed downloads with a 50 MB cap (512 MB for a video) from allow-listed HTTPS hosts, typed 402/429 errors that say what to do (details)

  • 2 runtime dependencies — @modelcontextprotocol/sdk + zod; native fetch

Related MCP server: ideogram-mcp-server

Quick Start

Requires Node.js 22 or newer and an IDEOGRAM_API_KEY — create one in Ideogram's API dashboard at ideogram.ai/platform → API Keys → Create key (setup guide).

claude mcp add --scope user ideogram -e IDEOGRAM_API_KEY=your-api-key -e IDEOGRAM_OUTPUT_DIR=/tmp/ideogram-output -- npx -y @qmediat.io/ideogram-mcp

or by hand (below). npm install -g @qmediat.io/ideogram-mcp installs the ideogram-mcp command, which can replace the npx line in any config.

Configuration

Claude Code

Add to ~/.claude.json → mcpServers:

{
  "ideogram": {
    "command": "npx",
    "args": ["-y", "@qmediat.io/ideogram-mcp"],
    "env": {
      "IDEOGRAM_API_KEY": "your-api-key",
      "IDEOGRAM_OUTPUT_DIR": "/tmp/ideogram-output"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ideogram": {
      "command": "npx",
      "args": ["-y", "@qmediat.io/ideogram-mcp"],
      "env": {
        "IDEOGRAM_API_KEY": "your-api-key",
        "IDEOGRAM_OUTPUT_DIR": "/tmp/ideogram-output"
      }
    }
  }
}

Environment Variables

Variable

Required

Default

Description

IDEOGRAM_API_KEY

Yes

—

Your Ideogram API key (ideogram.ai/platform → API Keys)

IDEOGRAM_OUTPUT_DIR

No

/tmp/ideogram-output

Any folder where you want images saved. Use absolute paths (e.g. /home/user/images/ideogram)

Available Tools

Tool

What it does

Models

ideogram_generate

Images from a text prompt

ideogram-3 (default), ideogram-4-5, ideogram-4, ideogram-3-character, ideogram-3-custom-model, ideogram-4-custom-model, ideogram-3-transparent, ideogram-4-transparent, ideogram-2a, ideogram-2, gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, nano-banana-2, nano-banana-pro, p-image-ideogram, z-image, auto

ideogram_precise_edit

Edit an image at its exact size: a prompt, an optional mask (black = edit), up to 4 reference images, context_window to confine the edit

ideogram-4-5

ideogram_inpaint

Repaint the masked part of an image (black = repaint)

ideogram-3 (default), ideogram-3-character, ideogram-3-custom-model

ideogram_edit

The 1.x name of ideogram_inpaint (kept through 2.x)

as inpaint

ideogram_remix

New images from a source image and a prompt

ideogram-3 (default), ideogram-3-character, ideogram-3-custom-model, ideogram-4, auto

ideogram_reframe

Extend an image to a new size (outpainting)

ideogram-3 (default), nano-banana-2

ideogram_replace_background

A new background, the subject kept

ideogram-3 (default), gpt-image-2

ideogram_remove_background

The foreground as a transparent PNG

ideogram-1

ideogram_remove_object

Remove what the mask marks (white = remove) and fill the gap

ideogram-1

ideogram_upscale

Enlarge an image

auto (default), topaz-bloom-2, topaz-redefine, topaz-standard-2, topaz-text-refine, topaz-wonder-3-5, nano-banana-pro

ideogram_describe

Describe an image: words (ideogram-3, default) or a structured JSON prompt (ideogram-4)

ideogram-3, ideogram-4

ideogram_video_text

A video from a prompt: duration, aspect ratio, resolution, audio per model; saved as mp4 (give duration: omitted, Seedance is quoted at its maximum length)

seedance-2-5-text-to-video (default), seedance-2-text-to-video, kling-3-standard-text-to-video, minimax-h3-text-to-video

ideogram_video_image

A video from a start image (and an end image): files, URLs or assets

seedance-2-5-image-to-video (default), seedance-2-image-to-video, kling-3-standard-image-to-video, minimax-h3-image-to-video

ideogram_video_reference

A video guided by reference images, MP3/WAV clips (2-30 s on Seedance 2.5, 2-15 s elsewhere) and videos stored with Ideogram, in prompt order; at least one reference image or video

seedance-2-5-reference-to-video (default), seedance-2-reference-to-video, minimax-h3-reference-to-video

ideogram_layerize

A flat image as an editable design: the text-free base image (saved) and the detected text blocks (JSON: text, position, font, size, colour); optional font_candidate_files (.ttf, .otf, .woff, .woff2) to match against

ideogram-3

ideogram_ad_localizer

Translate an ad's copy into one language, keeping layout, logos and product; exact_copy pins wordings

one operation (post_ad_localizer)

ideogram_ad_resizer

Reframe an ad to a platform's exact ad size inside its safe zone

one operation (post_ad_resizer)

ideogram_ad_variations

Vary an ad along one axis: people, setting, group_size or scene

one operation (post_ad_variations)

ideogram_colorways

Recolor a product photo: up to 4 masks paired with hex colours

one operation (post_colorways)

ideogram_ghost_mannequin

A garment on an invisible mannequin from its photos, in the view asked

one operation (post_ghost_mannequin)

ideogram_material_swap

Apply reference materials to the masked regions of a product photo

one operation (post_material_swap)

ideogram_model_pose_variants

Re-pose the model of a fashion image by instruction

one operation (post_model_pose_variants)

ideogram_sketch_to_render

Render a fashion sketch as a product photo

one operation (post_sketch_to_render)

ideogram_magic_prompt

Rewrite a prompt into an Ideogram 4.0 structured JSON prompt (nothing generated)

one operation (post_magic_prompt_v4)

ideogram_layerize_logos

Detect and remove reference logos from a flat design: the base image saved, the layers listed

one operation (post_layerize_logos)

ideogram_provenance

Check whether an image was created by Ideogram (free)

one operation (post_provenance_verify)

ideogram_snap_mask

Snap a hand-drawn mask to the object it marks; the PNG saved

one operation (post_snap_mask)

ideogram_quote

The price of a call: {"tool": "ideogram_generate", "arguments": {…}}

every operation that offers a dry run (not describe, ad variations, pose variants, sketch to render, nor the v1 utilities)

ideogram_generation

Collect a generation by generation_id — its images or its video

—

ideogram_usage

Billed usage as Ideogram reports it: buckets of line items summed per product and currency, the buckets handed on (the shape ai-cost reads); default the last 7 days by day

—

ideogram_invoices

The organization's invoices with their line items (organization-admin key)

—

ideogram_api_keys

The organization's API keys, redacted (organization-admin key)

—

ideogram_datasets

Your training datasets: the list (searched by name) or one with its files and models

—

ideogram_dataset_upload

Images, .txt captions and .zip archives into a dataset (an existing one, or a new one from a name); local paths or public https URLs

—

ideogram_train

Train a custom model from a dataset of 15–100 images; hyperparameters route to the advanced operation

ideogram-4 (default), ideogram-3

ideogram_models

Your custom models and the shared ones, or one with its training runs; a completed model's custom_model_uri generates through ideogram_generate

—

ideogram_operations

What the API offers: families, operations, fields, limits

—

ideogram_api

Any served operation by id, including the ones the documentation index does not list (the reframe models auto, bria-expand, gpt-image-2-5-flare, nano-banana-pro)

—

Each model's fields are listed in the tool's schema (one variant per model) and in docs/API-REFERENCE.md, generated from the specification. Image inputs are local file paths or public https URLs (or Ideogram asset identifiers where a model takes them); each operation's own upload limits apply, checked each file against its field's limit before any is read, the whole encoded request against the request cap before it is sent.

A client without files: URL inputs and inline images

Any file field (image, images, mask, the reference and style images, the font files) takes a public https:// URL beside a local path: the file is fetched under the field's own limit and types, from a public host only (no IP address, no local name, no private address, no redirect), inside the call's budget, one input after another. inline_images: true on any tool that saves images returns each saved image under 3.75 MB, up to 10 MB per result, as image content beside the text (the others stay by path), so a client that cannot read this machine's files still sees the result. Both are off unless asked.

Usage, invoices, webhooks

ideogram_usage asks GET /v2/account/usage for a range (RFC 3339 times; 1d buckets over at most 92 days, 1h over at most 168 hours — the tool refuses a longer one before asking; the api and app sources) and answers with the sums per product, unit and currency — decimal strings, never floats; an amount it cannot read is counted, not summed — and writes the buckets exactly as Ideogram sent them to a JSON file in the output directory (named by the query, readable by the owner only — the line items carry member emails and key prefixes; printed too when under 64 KB): the shape a cost tool reads. The invoices and the API keys are written and shown the same way, and so is an answer off its specification (reported as such, never as a success). All three account tools need an API key owned by an organization admin (Ideogram answers 404 to any other key, and the tool says so with Ideogram's words).

Ideogram signs its webhooks with Ed25519: the canonical message is request_id\nuser_id\ntimestamp\nsha256_hex(body), the signature travels in X-Ideogram-Webhook-Signature (the key id in X-Ideogram-Webhook-Key-Id), the public keys are the JWKS at GET https://api.ideogram.ai/v1/.well-known/jwks.json (public; cache up to 24 h). Where request_id, user_id and timestamp travel is not stated by the specification (it names the two signature headers only): take them from the delivery as Ideogram's webhook documentation says. The receiver — not this server, which has no public URL — verifies with the helper this package ships; a delivery whose timestamp is more than maxAgeS (300 s by default; Infinity turns it off) from now is refused as a replay — the signature alone never expires:

import { verifyWebhook } from "@qmediat.io/ideogram-mcp/dist/webhooks.js";
const kid = verifyWebhook(
  { body, requestId, userId, timestamp, signature: headers["x-ideogram-webhook-signature"], keyId: headers["x-ideogram-webhook-key-id"] },
  jwks,
  { maxAgeS: 300 },
);
if (kid === null) reject(); // the key id that verified, else null

Training a custom model

Drop a folder of references: ideogram_dataset_upload {"name": "brand refs", "files": ["…/1.png", "…/1.txt", "…/more.zip"]} creates the dataset and uploads the assets (a caption sidecar x.txt goes with x.png; an archive may hold both), ideogram_train {"dataset_id": "…", "model_name": "Brand Refs"} starts an Ideogram 4.0 training ("model": "ideogram-3" for 3.0; training_steps, lora_rank, ema, learning_rate — and for 4.0 batch_size, base_variant, wandb_project — route to the advanced operation), ideogram_models {"model_id": "…"} follows it, and a COMPLETED model's custom_model_uri generates through ideogram_generate with model: "ideogram-4-custom-model". Training is billed by Ideogram per its plan; the tools say what was started, never start it twice.

Waiting, and collecting later

A generation is sent asynchronously and returned the moment Ideogram accepts it. The tool then waits up to wait_s seconds (default 45, at most 50: MCP clients time a call out at 60 s), polling at 2 s, ×1.5, up to 30 s apart. A job still running at the end of the wait comes back as its generation_id: ideogram_generation {"generation_id": "…"} collects it later, in this session or another. Sending the request again would start — and bill — a second job. Every tool call has one budget, fixed when it starts: 55 s (the caller's 60 s minus a margin), ended earlier by the caller's own cancellation (a client that times out or a user who cancels). Every request, retry sleep (Retry-After included), poll and download of the call is judged against what remains of it, so nothing of a call outlives its caller and a request that creates work is never resent after the caller has given up: a POST is resent only when the time left also covers an attempt as long as the one just rejected. A download the budget cuts is listed as not saved beside the generation id; ideogram_generation saves it in a new call. What that leaves open: an upload that needs more than 55 s cannot be served inside one MCP call at all; a request the budget cuts while it is in flight is reported as possibly accepted (never resent); and a job the API accepts after the caller gave up keeps an id nobody receives — a limit of the 60 s client, not of this server.

Prices

ideogram_quote sends exactly the request the tool would send, with Ideogram's dry_run: the answer is the price in USD and credits (at your account's credit rate), exact or an estimate with its upper bound; nothing is generated, stored or billed. Describe has no dry run, so it cannot be quoted. A completed generation shows the cost Ideogram reports for it. This server keeps no price table: prices are the API's, per request.

Compatibility with 1.x

Calls written for 1.x keep working through 2.x, and the result says what was mapped:

1.x input

2.0

ideogram_generate without model

ideogram-3, as before

model: "3.0" / "4.0"

ideogram-3 / ideogram-4

rendering_speed: "TURBO" / "DEFAULT" / "QUALITY"

turbo / default / quality on the models that take rendering_speed; quality: low / medium / high on those that take quality (Ideogram 4.5, GPT Image 2.5, P-Image)

rendering_speed: "FLASH"

refused (v2 has no FLASH) — quality: very_low on the models that offer it

magic_prompt, style_type, color_palette.name in capitals

lowercase

ideogram_edit

ideogram_inpaint

describe_model_version: "V_3"

model: "ideogram-3"

A 1.x field that the chosen v2 model does not take is refused with the models that take it (the changelog has the full table).

The raw call

ideogram_api runs any operation this release serves — the curated ones and every other /v2/image operation (the reframe models the documentation index does not list) — by its id, with its parameters kept in their places: {"operation": "…", "params": {"path": {}, "query": {}, "body": {}}, "files": [{"field": "image", "path": "…"}], "dry_run": false}. The parameters are checked against the operation's own schema and rules before anything is sent. Operations Ideogram's documentation does not list need allow_undocumented: true; web-app (Bearer) and internal operations are refused; the undocumented get_asset_reference_usage of the account family too; the customer-specific tools (skechers, swan, sole-swap) and the spec-only workflows run here and only here, behind allow_undocumented; the v1 model variants (ernie, flux-2 klein, the Ideogram 4.0 tiers, the P-Image tiers, design and graphic v3/v4) run here without opt-in — Ideogram documents them in its v1 reference (prefer an _async twin where one exists: a synchronous v1 generation must finish inside the call's budget); nothing is planned for a later release (plan).

Security

A defensive, minimal-dependency design:

  • SSRF protection — downloads over HTTPS only, from allow-listed hosts, redirects blocked; a URL given as an input is fetched from a public host only (no IP literal, no local name, no private or special-purpose address after resolution, no redirect), under the call's budget, over a connection pinned to the address that was judged (a DNS rebinding reaches nothing)

  • Symlink rejection — lstat() rejects a symlinked input file before reading (a symlinked parent directory is resolved)

  • Upload limits per operation — each file checked with stat() against its field's limit before any is read; the local file name is never sent (a file goes as <field>.<ext>) — except a training asset's own name (never its directory), which the API pairs captions by

  • Streamed, capped downloads — written to disk with a byte counter, stopped at 50 MB (512 MB for a video), the partial file removed; a video that cannot download within the call's budget (55 s) is "Not saved" with its link, for you to fetch before it expires; image/* or video/mp4 required

  • Schema validation — inputs against each model's generated schema before any request; a success response the specification's schema rejects is reported as a contract mismatch, never as a success

  • Input paths — the model may name any readable image file on the machine for upload; run the server as a user whose readable images you are willing to send to Ideogram

Full details in SECURITY.md.

Development

git clone https://github.com/qmediat/ideogram-mcp.git
cd ideogram-mcp
npm install
npm run build
npm run typecheck
npm run lint        # structure rules, repeated blocks, the baseline ratchet (docs/SYSTEMIC.md §1)
npm run format      # Prettier (npm run lint checks it)
npm test            # builds, then every test against a fake API (no key, no network); with IDEOGRAM_API_KEY set, the live dry-run suite runs too (below)

The specification snapshot drives the code: npm ci --prefix scripts/spec-gen && npm run spec:generate regenerates src/generated/ (CI checks it with npm run spec:check), npm run docs:api the API reference, npm run spec:pull compares the live specification with the snapshot. These scripts need Node.js 22.18 or newer (type stripping), and so does npm run lint (its Babel 8 parser: 22.18+ or 24.11+). With IDEOGRAM_API_KEY set, test/live-dry-run.test.mjs quotes every curated model at no cost and writes the prices to docs/PRICES-<date>.md.

Run locally:

IDEOGRAM_API_KEY=your-key node dist/index.js

Contributing

See CONTRIBUTING.md for architecture guidelines and PR requirements.

Trademarks and affiliation

Ideogram is a trademark of Ideogram. This is an independent, community-maintained integration published by Quantum Media Technologies sp. z o.o.; it is not affiliated with, sponsored by or endorsed by Ideogram. Use of the Ideogram API through this server is subject to Ideogram's own terms and to your own API key or account.

License

MIT — Quantum Media Technologies

Made by Quantum Media Technologies · more open source from qmediat

Available Tools

7 tools
ideogram_describeA

Generate a text description of an image (Ideogram's describe endpoint). Accepts a local file path.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesLocal file path of the image to describe
describe_model_versionNoModel version to use (default: V_3)

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses the input shape ('local file path') and the output category ('text description'), but says nothing about permissions, whether the source file is modified, cost, or how model version changes results. Adequate but thin for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action, with no filler. The second sentence is somewhat redundant with the schema's image parameter, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (2 params, 1 required, no output schema), and the description covers action, input, and output type, which is largely sufficient. Minor gaps around model-version tradeoffs and output format remain, but nothing an agent needs to invoke it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (image path and describe_model_version enum) are already documented in the schema. The description's 'Accepts a local file path' merely restates the schema and adds no new semantics, matching the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('generate a text description of an image') and names the backing endpoint, which clearly separates it from the image-mutation siblings (generate, edit, upscale, reframe). It stops short of explicitly contrasting itself with those siblings, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call this when you need a caption/description of an existing image rather than a new or edited one. There is no explicit when-to-use/when-not statement or named alternative, but the sibling set makes the selection fairly obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ideogram_editB

Edit specific areas of an image using mask-based inpainting. Requires source image, mask (black=edit, white=keep), and prompt; takes the style and character references, style codes, preset and palette (no exact resolution: inpaint keeps the source size).

ParametersJSON Schema
NameRequiredDescriptionDefault
maskYesLocal file path of the mask image (black = regions to edit, white = keep)
seedNoReproducibility seed
imageYesLocal file path of the source image to edit
promptYesDescription of desired changes
num_imagesNoNumber of variations (1-8, default: 1)
style_typeNoVisual style (the API default is GENERAL when omitted)
style_codesNo8-character hexadecimal style codes from Ideogram
magic_promptNoAuto-enhance prompts (default: AUTO)
style_presetNoA named style preset as Ideogram lists them
color_paletteNoA preset palette by name, or explicit colours with weights (not both)
rendering_speedNoSpeed/quality tradeoff (default: DEFAULT)
style_reference_imagesNoLocal image files whose style the result follows (up to 3, 25 MB each)
character_reference_maskNoGrayscale mask of the character reference (same dimensions); needs character_reference_image
character_reference_imageNoLocal image file of a character to keep consistent (one image; Ideogram bills character references at its own rate)

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does disclose useful behavior: mask semantics, required inputs, and that inpainting keeps the source resolution. However, it omits return format, side effects, auth/cost context, and other operational traits an agent would need for a mutation-style image edit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and avoids filler. It is somewhat dense with semicolons and parentheticals, but every clause contributes relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter tool with no annotations and no output schema, the description is adequate but incomplete: it does not explain what the tool returns or how many images/variations are produced. The rich input schema covers parameters, reducing the burden, but output and operational context remain gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 14 parameters in detail. The description summarizes optional style/character inputs and adds the resolution caveat, but adds little parameter-level meaning beyond what the structured schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Edit specific areas of an image using mask-based inpainting.' This is clear and method-specific, distinguishing it practically from upscale/reframe/background-replacement siblings, but it does not explicitly name or compare against any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the mask-based inpainting method and the listed required inputs (source image, mask, prompt), but there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The agent can infer the context but is not routed between this and siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ideogram_generateB

Generate images from text prompts with Ideogram 3.0 (default) or 4.0 (model: '4.0'). 3.0 takes aspect ratios or an exact resolution, style types, style and character reference images, style codes, presets, colour palettes and custom models.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoReproducibility seed (0-2,147,483,647)
modelNoIdeogram model: 3.0 (default; every parameter below) or 4.0 (text prompt, resolution, rendering_speed except FLASH, enable_copyright_detection — the other parameters are refused)
promptYesImage description (1-10,000 characters)
num_imagesNoNumber of images to generate (1-8, default: 1)
resolutionNoExact output resolution: one of Ideogram 3.0's 69 sizes, or any WIDTHxHEIGHT for model 4.0; not with aspect_ratio
style_typeNoVisual style (the API default is GENERAL when omitted)
style_codesNo8-character hexadecimal style codes from Ideogram
aspect_ratioNoOutput aspect ratio (default: 1x1)
magic_promptNoAuto-enhance prompts (default: AUTO)
style_presetNoA named style preset as Ideogram lists them
color_paletteNoA preset palette by name, or explicit colours with weights (not both)
negative_promptNoWhat to exclude from the generated image
rendering_speedNoSpeed/quality tradeoff. FLASH=fastest, QUALITY=best (default: DEFAULT)
custom_model_uriNoA custom (trained) model: model/<name>/version/<version>
style_reference_imagesNoLocal image files whose style the result follows (up to 3, 25 MB each)
character_reference_maskNoGrayscale mask of the character reference (same dimensions); needs character_reference_image
character_reference_imageNoLocal image file of a character to keep consistent (one image; Ideogram bills character references at its own rate)
enable_copyright_detectionNotrue runs Ideogram's copyright detection on this request; false leaves the organisation setting in force (it cannot switch an organisation-wide detection off)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, yet it offers no cost, rate-limit, latency, or output-handling information. The feature list for 3.0 largely duplicates what the schema already documents, adding minimal behavioral insight beyond the default-model note.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with the model/version distinction front-loaded. The second sentence is a somewhat loose enumeration, but it stays short and every clause maps to real capability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter generative tool with no annotations and no output schema, the description is thin: it says nothing about return values, asynchronous generation, or billing implications of reference images. It does not compensate for the absent structured context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each of the 18 parameters is already documented in detail. The description's parameter mentions (aspect ratios, resolution, style codes, presets, palettes) restate schema content without adding format or interaction detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Generate images from text prompts') and identifies the two model versions with the default flagged. It doesn't differentiate itself from siblings like ideogram_edit or ideogram_remix, but the core purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It notes that 3.0 is the default and that 4.0 is opt-in via model: '4.0', and lists what 3.0 supports, which implicitly guides model choice. However it never states when to prefer 4.0 over 3.0, nor when to use this tool versus edit/remix/upscale siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ideogram_reframeB

Extend an image to a new resolution via outpainting. Specify target resolution (e.g. 1024x1024, 1536x640).

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoReproducibility seed
imageYesLocal file path of the source image to reframe
num_imagesNoNumber of variations (1-8, default: 1)
resolutionYesTarget resolution (e.g. 1024x1024, 1536x640). See Ideogram docs for all 69 valid resolutions.
rendering_speedNoSpeed/quality tradeoff (default: DEFAULT)

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It only says the operation is outpainting; it does not state whether the original file is modified, what kind of result is returned, whether output is saved to disk, or how the reframed image is delivered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, no filler, and the core action is front-loaded. The example target resolutions are helpful and directly relevant to the required resolution parameter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should explain what the tool returns or produces after outpainting, but it does not. It also omits behavior around num_images and rendering_speed, leaving an agent without enough context to fully understand the call's result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter already has a description, so the baseline is 3. The description adds only an example resolution format, which the schema's enum already covers, and provides no additional meaning for seed, num_images, or rendering_speed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Extend an image to a new resolution via outpainting.' This clearly communicates the core operation and distinguishes it from siblings like upscale, edit, and remix by naming the outpainting technique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through 'extend an image to a new resolution via outpainting,' but it never explicitly says when to choose this over siblings or when not to use it. No alternatives are named, leaving the agent to infer selection from the verb alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ideogram_remixC

Transform an image with a new prompt while preserving characteristics. Control influence with image_weight (0-100); takes the style and character references, style codes, preset, palette and an exact resolution.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoReproducibility seed
imageYesLocal file path of the source image to remix
promptYesNew creative direction
num_imagesNoNumber of variations (1-8, default: 1)
resolutionNoExact output resolution (one of Ideogram's 69 sizes); not with aspect_ratio
style_typeNoVisual style (the API default is GENERAL when omitted)
style_codesNo8-character hexadecimal style codes from Ideogram
aspect_ratioNoOutput aspect ratio
image_weightNoOriginal image influence (0-100, default: 50)
magic_promptNoAuto-enhance prompts (default: AUTO)
style_presetNoA named style preset as Ideogram lists them
color_paletteNoA preset palette by name, or explicit colours with weights (not both)
negative_promptNoWhat to exclude
rendering_speedNoSpeed/quality tradeoff (default: DEFAULT)
style_reference_imagesNoLocal image files whose style the result follows (up to 3, 25 MB each)
character_reference_maskNoGrayscale mask of the character reference (same dimensions); needs character_reference_image
character_reference_imageNoLocal image file of a character to keep consistent (one image; Ideogram bills character references at its own rate)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It hints at what inputs are accepted (style/character references, style codes, preset, palette, exact resolution) but says nothing about cost, permissions, latency, rate limits, or what the tool returns. The one genuinely behavioral detail, image_weight influencing fidelity to the source, is thin for a 17-parameter generation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the core action front-loaded and the control knob second. The second sentence is a bit of a parameter list, but nothing is padded or redundant in a wasteful way.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter image-generation tool with no annotations and no output schema, the description is inadequate: it omits how the tool differs from sibling remix/edit tools, does not explain interactions among the style inputs, and says nothing about results or cost despite character references carrying billing implications.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter including ranges and mutual exclusions (resolution vs aspect_ratio). The description adds the image_weight (0-100) range, which merely repeats the schema, and otherwise only names a subset of the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: transform an image with a new prompt while preserving its characteristics. It reads clearly as an image-to-image remix, but never names or contrasts itself with the closest siblings (ideogram_edit, ideogram_generate), leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no when-not-to-use, and no mention of alternatives. The only usage-flavored sentence is about tuning image_weight, which is a knob, not a selection criterion between this tool and ideogram_edit or ideogram_generate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ideogram_replace_backgroundB

Replace the background of an image while preserving the foreground subject. Describe the new background in the prompt.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoReproducibility seed
imageYesLocal file path of the source image
promptYesDescription of the new background
num_imagesNoNumber of variations (1-8, default: 1)
magic_promptNoAuto-enhance prompts (default: AUTO)
rendering_speedNoSpeed/quality tradeoff (default: DEFAULT)

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden for behavioral disclosure. It does state one behavioral trait—preserving the foreground subject—which is helpful, but it does not disclose the output format, whether the input file is modified or a new file is generated, or any side effects. This is insufficient for a mutation tool with no schema description of return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the core action and the prompt requirement with no filler. It is appropriately concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with six parameters and no output schema, the description is quite sparse. It does not mention that the output is an image, how many variations are produced by default, or the effect of optional parameters like 'num_images' or 'rendering_speed'. These are present in the schema but the description does not tie them together for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description's instruction to 'Describe the new background in the prompt' essentially repeats the schema's definition of the 'prompt' parameter, adding no new insight. No other parameters are mentioned in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Replace'), names the resource ('background of an image'), and adds a distinguishing constraint ('preserving the foreground subject'). This clearly differentiates it from siblings like ideogram_generate or ideogram_describe, so an agent can select it correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description only states what the tool does and how to use the prompt, but does not provide any explicit guidance on when to choose this tool over alternatives like ideogram_edit or ideogram_reframe. Usage is only implied by the tool's name and purpose, with no exclusion or alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ideogram_upscaleB

Upscale an image to higher resolution with guided enhancement. Control resemblance (0-100) and detail (0-100).

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoReproducibility seed
imageYesLocal file path of the image to upscale
detailNoDetail to add (0-100, default: 50)
promptNoGuide the upscaling enhancement
num_imagesNoNumber of variations (1-8, default: 1)
resemblanceNoSimilarity to original (0-100, default: 50)
magic_promptNoAuto-enhance prompts (AUTO/ON/OFF)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility. It mentions 'guided enhancement' and the resemblance/detail controls but does not disclose side effects, output format, or whether the original image is modified. It lacks any mention of rate limits or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence that front-loads the core purpose and mentions the two most relevant controls. Every word earns its place, with no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters, no output schema, and no annotations, the description is grossly insufficient. It omits crucial details such as how the output is returned, how to use the prompt, what magic_prompt does, and any side effects or prerequisites. An agent would struggle to invoke this correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters (100% coverage), so the baseline is 3. The description adds marginal value by highlighting resemblance and detail as key controls, but it does not explain the prompt, seed, num_images, or magic_prompt parameters beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Upscale') and resource ('an image to higher resolution'), and the 'guided enhancement' phrase adds context. It clearly distinguishes from sibling tools like generate, edit, or remix, which perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the other ideogram tools. It does not mention that this is for upscaling only, nor does it exclude other use cases or reference alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.2.0
    • Changedideogram_edit9 fields changed
      • addedInput schema / additionalProperties
        Added value: +false
      • addedInput schema / properties / character_reference_image
        Added value: +{
+  "description": "Local image file of a character to keep consistent (one image; Ideogram bills character references at its own rate)",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / character_reference_mask
        Added value: +{
+  "description": "Grayscale mask of the character reference (same dimensions); needs character_reference_image",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / color_palette
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "description": "A preset palette",
+          "enum": [
+            "EMBER",
+            "FRESH",
+            "JUNGLE",
+            "MAGIC",
+            "MELON",
+            "MOSAIC",
+            "PASTEL",
+            "ULTRAMARINE"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "members": {
+          "description": "Explicit colours, most dominant first",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "color_hex": {
+                "description": "The colour, #RRGGBB",
+                "pattern": "^#[0-9A-Fa-f]{6}$",
+                "type": "string"
+              },
+              "color_weight": {
+                "description": "Its share of the palette (0.05-1)",
+                "maximum": 1,
+                "minimum": 0.05,
+                "type": "number"
+              }
+            },
+            "required": [
+              "color_hex"
+            ],
+            "type": "object"
+          },
+          "maxItems": 10,
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "members"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "A preset palette by name, or explicit colours with weights (not both)"
+}
      • changedInput schema / properties / mask / description
        Previous value: -"Local file path of the mask image (black=edit, white=keep, min 10% black)"New value: +"Local file path of the mask image (black = regions to edit, white = keep)"
      • addedInput schema / properties / style_codes
        Added value: +{
+  "description": "8-character hexadecimal style codes from Ideogram",
+  "items": {
+    "pattern": "^[0-9A-Fa-f]{8}$",
+    "type": "string"
+  },
+  "maxItems": 8,
+  "minItems": 1,
+  "type": "array"
+}
      • addedInput schema / properties / style_preset
        Added value: +{
+  "description": "A named style preset as Ideogram lists them",
+  "maxLength": 100,
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / style_reference_images
        Added value: +{
+  "description": "Local image files whose style the result follows (up to 3, 25 MB each)",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}
      • changedInput schema / properties / style_type / description
        Previous value: -"Visual style (default: AUTO)"New value: +"Visual style (the API default is GENERAL when omitted)"
    • Changedideogram_generate12 fields changed
      • addedInput schema / additionalProperties
        Added value: +false
      • addedInput schema / properties / character_reference_image
        Added value: +{
+  "description": "Local image file of a character to keep consistent (one image; Ideogram bills character references at its own rate)",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / character_reference_mask
        Added value: +{
+  "description": "Grayscale mask of the character reference (same dimensions); needs character_reference_image",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / color_palette
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "description": "A preset palette",
+          "enum": [
+            "EMBER",
+            "FRESH",
+            "JUNGLE",
+            "MAGIC",
+            "MELON",
+            "MOSAIC",
+            "PASTEL",
+            "ULTRAMARINE"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "members": {
+          "description": "Explicit colours, most dominant first",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "color_hex": {
+                "description": "The colour, #RRGGBB",
+                "pattern": "^#[0-9A-Fa-f]{6}$",
+                "type": "string"
+              },
+              "color_weight": {
+                "description": "Its share of the palette (0.05-1)",
+                "maximum": 1,
+                "minimum": 0.05,
+                "type": "number"
+              }
+            },
+            "required": [
+              "color_hex"
+            ],
+            "type": "object"
+          },
+          "maxItems": 10,
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "members"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "A preset palette by name, or explicit colours with weights (not both)"
+}
      • addedInput schema / properties / custom_model_uri
        Added value: +{
+  "description": "A custom (trained) model: model/<name>/version/<version>",
+  "pattern": "^model\\/[^/\\s]+\\/version\\/[^/\\s]+$",
+  "type": "string"
+}
      • addedInput schema / properties / enable_copyright_detection
        Added value: +{
+  "description": "true runs Ideogram's copyright detection on this request; false leaves the organisation setting in force (it cannot switch an organisation-wide detection off)",
+  "type": "boolean"
+}
      • addedInput schema / properties / model
        Added value: +{
+  "description": "Ideogram model: 3.0 (default; every parameter below) or 4.0 (text prompt, resolution, rendering_speed except FLASH, enable_copyright_detection — the other parameters are refused)",
+  "enum": [
+    "3.0",
+    "4.0"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / resolution
        Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "512x1536",
+        "576x1408",
+        "576x1472",
+        "576x1536",
+        "640x1344",
+        "640x1408",
+        "640x1472",
+        "640x1536",
+        "704x1152",
+        "704x1216",
+        "704x1280",
+        "704x1344",
+        "704x1408",
+        "704x1472",
+        "736x1312",
+        "768x1088",
+        "768x1216",
+        "768x1280",
+        "768x1344",
+        "800x1280",
+        "832x960",
+        "832x1024",
+        "832x1088",
+        "832x1152",
+        "832x1216",
+        "832x1248",
+        "864x1152",
+        "896x960",
+        "896x1024",
+        "896x1088",
+        "896x1120",
+        "896x1152",
+        "960x832",
+        "960x896",
+        "960x1024",
+        "960x1088",
+        "1024x832",
+        "1024x896",
+        "1024x960",
+        "1024x1024",
+        "1088x768",
+        "1088x832",
+        "1088x896",
+        "1088x960",
+        "1120x896",
+        "1152x704",
+        "1152x832",
+        "1152x864",
+        "1152x896",
+        "1216x704",
+        "1216x768",
+        "1216x832",
+        "1248x832",
+        "1280x704",
+        "1280x768",
+        "1280x800",
+        "1312x736",
+        "1344x640",
+        "1344x704",
+        "1344x768",
+        "1408x576",
+        "1408x640",
+        "1408x704",
+        "1472x576",
+        "1472x640",
+        "1472x704",
+        "1536x512",
+        "1536x576",
+        "1536x640"
+      ],
+      "type": "string"
+    },
+    {
+      "pattern": "^\\d{3,4}x\\d{3,4}$",
+      "type": "string"
+    }
+  ],
+  "description": "Exact output resolution: one of Ideogram 3.0's 69 sizes, or any WIDTHxHEIGHT for model 4.0; not with aspect_ratio"
+}
      • addedInput schema / properties / style_codes
        Added value: +{
+  "description": "8-character hexadecimal style codes from Ideogram",
+  "items": {
+    "pattern": "^[0-9A-Fa-f]{8}$",
+    "type": "string"
+  },
+  "maxItems": 8,
+  "minItems": 1,
+  "type": "array"
+}
      • addedInput schema / properties / style_preset
        Added value: +{
+  "description": "A named style preset as Ideogram lists them",
+  "maxLength": 100,
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / style_reference_images
        Added value: +{
+  "description": "Local image files whose style the result follows (up to 3, 25 MB each)",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}
      • changedInput schema / properties / style_type / description
        Previous value: -"Visual style (default: AUTO)"New value: +"Visual style (the API default is GENERAL when omitted)"
    • Changedideogram_remix9 fields changed
      • addedInput schema / additionalProperties
        Added value: +false
      • addedInput schema / properties / character_reference_image
        Added value: +{
+  "description": "Local image file of a character to keep consistent (one image; Ideogram bills character references at its own rate)",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / character_reference_mask
        Added value: +{
+  "description": "Grayscale mask of the character reference (same dimensions); needs character_reference_image",
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / color_palette
        Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "description": "A preset palette",
+          "enum": [
+            "EMBER",
+            "FRESH",
+            "JUNGLE",
+            "MAGIC",
+            "MELON",
+            "MOSAIC",
+            "PASTEL",
+            "ULTRAMARINE"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "properties": {
+        "members": {
+          "description": "Explicit colours, most dominant first",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "color_hex": {
+                "description": "The colour, #RRGGBB",
+                "pattern": "^#[0-9A-Fa-f]{6}$",
+                "type": "string"
+              },
+              "color_weight": {
+                "description": "Its share of the palette (0.05-1)",
+                "maximum": 1,
+                "minimum": 0.05,
+                "type": "number"
+              }
+            },
+            "required": [
+              "color_hex"
+            ],
+            "type": "object"
+          },
+          "maxItems": 10,
+          "minItems": 1,
+          "type": "array"
+        }
+      },
+      "required": [
+        "members"
+      ],
+      "type": "object"
+    }
+  ],
+  "description": "A preset palette by name, or explicit colours with weights (not both)"
+}
      • addedInput schema / properties / resolution
        Added value: +{
+  "description": "Exact output resolution (one of Ideogram's 69 sizes); not with aspect_ratio",
+  "enum": [
+    "512x1536",
+    "576x1408",
+    "576x1472",
+    "576x1536",
+    "640x1344",
+    "640x1408",
+    "640x1472",
+    "640x1536",
+    "704x1152",
+    "704x1216",
+    "704x1280",
+    "704x1344",
+    "704x1408",
+    "704x1472",
+    "736x1312",
+    "768x1088",
+    "768x1216",
+    "768x1280",
+    "768x1344",
+    "800x1280",
+    "832x960",
+    "832x1024",
+    "832x1088",
+    "832x1152",
+    "832x1216",
+    "832x1248",
+    "864x1152",
+    "896x960",
+    "896x1024",
+    "896x1088",
+    "896x1120",
+    "896x1152",
+    "960x832",
+    "960x896",
+    "960x1024",
+    "960x1088",
+    "1024x832",
+    "1024x896",
+    "1024x960",
+    "1024x1024",
+    "1088x768",
+    "1088x832",
+    "1088x896",
+    "1088x960",
+    "1120x896",
+    "1152x704",
+    "1152x832",
+    "1152x864",
+    "1152x896",
+    "1216x704",
+    "1216x768",
+    "1216x832",
+    "1248x832",
+    "1280x704",
+    "1280x768",
+    "1280x800",
+    "1312x736",
+    "1344x640",
+    "1344x704",
+    "1344x768",
+    "1408x576",
+    "1408x640",
+    "1408x704",
+    "1472x576",
+    "1472x640",
+    "1472x704",
+    "1536x512",
+    "1536x576",
+    "1536x640"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / style_codes
        Added value: +{
+  "description": "8-character hexadecimal style codes from Ideogram",
+  "items": {
+    "pattern": "^[0-9A-Fa-f]{8}$",
+    "type": "string"
+  },
+  "maxItems": 8,
+  "minItems": 1,
+  "type": "array"
+}
      • addedInput schema / properties / style_preset
        Added value: +{
+  "description": "A named style preset as Ideogram lists them",
+  "maxLength": 100,
+  "minLength": 1,
+  "type": "string"
+}
      • addedInput schema / properties / style_reference_images
        Added value: +{
+  "description": "Local image files whose style the result follows (up to 3, 25 MB each)",
+  "items": {
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}
      • changedInput schema / properties / style_type / description
        Previous value: -"Visual style (default: AUTO)"New value: +"Visual style (the API default is GENERAL when omitted)"
  2. 7 tool updatesv1.0.3
    • First observedideogram_describe
    • First observedideogram_edit
    • First observedideogram_generate
    • First observedideogram_reframe
    • First observedideogram_remix
    • First observedideogram_replace_background
    • First observedideogram_upscale
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a clearly distinct image operation: generation, description, background replacement, upscaling, masked inpainting, remixing, and outpainting. Although all modify images, the required inputs (mask, image_weight, target resolution) and descriptions make the boundaries unambiguous.

Naming Consistency5/5

All tool names follow a consistent pattern: ideogram_ prefix plus a clear verb or verb_noun (generate, describe, replace_background, upscale, edit, remix, reframe). No mixing of conventions or case styles.

Tool Count5/5

Seven tools is a well-scoped set for an image generation and editing API, covering core generation and advanced manipulation without bloat or notable omissions. Each tool earns its place.

Completeness5/5

The surface covers the full lifecycle of image creation and transformation: text-to-image, image description, background replacement, upscaling, masked editing, remixing, and outpainting. No obvious operational gaps for the stated Ideogram domain.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers