Bulk Image Generation Workflow

Bulk Image Generation Workflow

This skill orchestrates around one tool: mcp__ideogram__generate_images_bulk(prompts: list[str], ...). It accepts 1–500 prompt strings and submits them as one async background job; results render into a carousel as each image completes rather than blocking on the whole batch.

The constraint the whole skill is built on: every non-prompt parameter (aspect_ratio, resolution, rendering_speed, style_type, negative_prompt, seed, magic_prompt_option, custom_model_uri, collection_id, private) is shared across the entire batch — there is no per-prompt override. On-brief variation at scale has to come from differences in the prompt text itself, not from differences in call parameters. Note the caveat: style_type, negative_prompt, seed, and magic_prompt_option only take effect when custom_model_uri is set (the custom-model v3 path); on the default v4 path they're ignored, so passing them there does nothing.

This skill sits between collections-management's pure-orchestration pattern and the pure prompt-composition skills' pattern: mostly orchestration, with one prompt-composition component — turning one caption into N prompts — covered by references/variation-strategy.md.

Before you start

Read references/variation-strategy.md before drafting the prompt array (steps 2–3 below) and references/review-culling-guide.md before reviewing results (step 6 below). Both apply before you touch the workflow.

Workflow

1. Resolve the base caption

Use an existing locked structured JSON caption if the user or project context already has one. Otherwise build one quickly using skills/ideogram-prompt/references/json-caption-schema.md's schema and ideogram-prompt/SKILL.md's precise-mode guidance, rather than re-deriving the schema here. This caption's style_description object is what stays locked for the whole batch.

2. Choose the variation axis

Per references/variation-strategy.md, decide what changes per prompt — pose, prop, angle, framing, a swapped compositional_deconstruction element — while style_description stays byte-for-byte identical across every prompt in the batch. If the axis isn't obvious from the user's request, confirm it with them before drafting.

3. Draft the N-prompt array

Write each variation as a prompt string, using either JSON-in-prompt or schema-structured prose per ideogram-prompt's two modes, producing the prompts list argument. Enforce the 1–500 bound before submitting: if the requested variation count would exceed 500, ask the user to narrow the axis or split into multiple generate_images_bulk calls rather than truncating the list.

4. Confirm batch size before submitting

There's no dry-run or preview for this tool, and every image in the batch spends generation credits on submission. For anything past a small batch (roughly 20+ prompts — a chosen default for this skill, not a threshold the API itself enforces), get an explicit go-ahead on the count before calling generate_images_bulk — the same spend-before-you-commit spirit collections-management applies to destructive flags, adapted here to spend instead of deletion.

5. Submit and track

Call generate_images_bulk(prompts=[...], ...) once, passing the shared non-prompt parameters the user specified (noting the custom-model-only params caveat from the intro above). Tell the user it's an async job and they can keep chatting while it renders. Use get_generation_status(request_id=...) — or omit request_id to list everything from the session — to check progress. Its response is a markdown table of Request ID | Status | Prompt | URL rows in terminal hosts, with the same data available in structured_content.rows. The exact shape generate_images_bulk itself returns for a multi-prompt submission (one batch-level identifier vs. one row per prompt) should be read from the actual response the first time it's called in a session, not assumed in advance — the same discipline collections-management/references/collection-patterns.md applies to unconfirmed field shapes.

6. Review and cull

Once results are available, follow references/review-culling-guide.md: pull results via get_generation_status (or get_recent_generations(n=..., filter_mode="GENERATIONS") as a fallback lookup), score each image against the locked style_description and its own per-prompt compositional intent, record a one-line keep/reject reason per image, and produce a shortlist. Hand the shortlist to collections-management to file it and to upscale_image for any finals that need higher resolution — this skill doesn't reimplement either.

Error handling

• Batch count outside 1–500 → ask the user to narrow the axis or split into multiple calls; never silently truncate or pad the prompt list to fit.
• Large-batch submission without explicit size confirmation → don't submit; ask first, since there's no dry-run and every image spends credits the moment it's submitted. The "roughly 20+ prompts" size that triggers this check is a chosen default for this skill, not a tool-enforced rule — apply judgment, don't treat it as an API cutoff.
• A drafted prompt that changes style_description fields instead of only compositional_deconstruction → flag it during drafting (or in review, if it slipped through) as off-brief; fix the prompt or split it into a separate batch rather than letting one drifted prompt sit in an otherwise-locked batch.
• Partial batch failure (some prompts fail to render or return a safety-filter-blocked placeholder) → surface the real per-item outcome; a blocked or failed image is a reportable failure, not a keeper, and the batch is not "fully successful" just because most of it rendered.
• Unconfirmed response shape from generate_images_bulk → read what the actual response contains rather than asserting a specific field name or structure in advance; report what was actually observed.
• Bad batch (most images miss the brief on review) → per references/review-culling-guide.md, revise the drifting part of the caption or the variation axis and resubmit a smaller follow-up batch; don't resubmit the full original count unchanged and hope for a different result.

Save what you made

After drafting the prompt array, submitting, and reviewing, save the locked caption, the full prompts array actually submitted, the request_id(s) from generate_images_bulk, and the keep/reject shortlist with reasons to the project's existing output location, rather than leaving them only in the conversation, per the toolkit's "No Context Lost" habit.

Reference files

• references/variation-strategy.md — how to pick a variation axis and draft N prompts that vary only that axis while keeping style_description locked. Read before step 2 or
• references/review-culling-guide.md — how to score generated images against the locked caption and per-prompt intent, and how to shortlist or resubmit a bad batch. Read before step 6.