Generation tools#

This page is the API reference for the generation-flow MCP tools — the zencreator_* tools your AI client uses to discover what ZenCreator can do, price a job, submit it, and read back results.

These are MCP tools. They are distinct from generation tools (the tool_name values like by_prompt, image_editor, videogen, faceswap, upscaler, lipsync) and the models you pass into them — those are documented in models. For the difference between a task and a call, see concepts. To turn the results of a task into viewable or downloadable files, see assets.

Typical flow#

1. Discover — zencreator_list_tools to pick a tool_name, then zencreator_get_tool_schema to learn its input shape, model list, prompt guide, and the questions to ask the user.
2. Price — zencreator_estimate_price (one candidate input) or zencreator_compare_prices (all models, cheapest first). State the cost to the user before committing.
3. Submit — zencreator_create_task (async; returns a task id) or zencreator_run_and_wait (blocks until terminal, then auto-fetches outputs and asset ids — images only, not video).
4. Poll & read — zencreator_get_task to check status, then zencreator_get_call_result to read a completed call's full output and asset ids.
5. Deliver — hand the asset ids to the asset tools for preview or download URLs.

Every tool below also accepts response_format ("markdown" default, or "json") and always returns a full machine-readable structuredContent object regardless of format. Responses over ~25,000 characters are truncated with a hint to paginate or switch to response_format: "json".

Discovery#

zencreator_list_tools#

List every available generation tool with its base credit price and current availability.

Parameters

Returns — structuredContent:

• count — number of tools returned.
• tools[] — each: name (the tool_name you pass to zencreator_create_task), description, price (base credits; final cost varies by inputs), blocked (boolean), and blocked_models (string array, present only when blocked; ["*"] means all models disabled).

The markdown view also embeds a tool-selection guide that maps common user intents to the right tool_name — read it before choosing a tool.

Errors

• Standard transport / auth errors only. Returns the full list otherwise.

Example — "What tools can generate video?" Ask your agent to list tools and filter by name/description containing "video".

zencreator_get_tool_schema#

Return the full input and output JSON Schema for a single generation tool, plus prompt-engineering guidance, model-selection criteria, and the standard questions to ask the user. Call this before submitting.

Parameters

Returns — structuredContent:

• name, description, price.
• input_schema — JSON Schema of expected inputs. Where the tool exposes resolution / output_format, they are promoted to required so they can't be silently defaulted.
• output_schema — JSON Schema of the output.
• models[] (optional) — every valid model value: value, description, optional is_default, trusted_only, input_constraints, output_traits, modes, pricing, notes. The model field in input_schema shows type: str with no enum — rely on this array for valid model values.
• prompt_guide (optional) — rules for writing the prompt field. Treat it as a contract.
• model_selection_guide (optional) — decision tree for picking model.
• format_questions[] (optional) — questions to ask the user before submission (count, aspect ratio, NSFW vs SFW, model preference, etc.).

Errors

• 404 — tool_name not recognised. Call zencreator_list_tools for valid names.

Example — "Edit this photo to replace the dress." Ask your agent to fetch the schema for image_editor; its prompt_guide explains the structure that produces better edits.

zencreator_get_model_prompt_guide#

Return a focused, per-model prompt-engineering guide for a specific image model. Each supported model has very different conventions, and using the wrong style degrades output quality.

Parameters

Returns — structuredContent:

• model — the echoed model value.
• prompt_guide — multi-section markdown: template, length, key rules, anti-patterns, NSFW technique, and an example.

Errors

• isError if the model name has no dedicated guide. The message lists the models that do; for any other model, fall back to the tool-level prompt_guide from zencreator_get_tool_schema.

When to call: after zencreator_get_tool_schema returns a model marked "has prompt guide" and you have picked which model to use — but before writing the prompt string you pass to zencreator_create_task / zencreator_run_and_wait.

Pricing#

Both pricing tools take two separate top-level fields: tool_name and params. params is the flat shape of ONE element of zencreator_create_task's inputs[] array — do not wrap it in { inputs: [...] } or nest tool_name inside it. A malformed call returns a corrected, ready-to-resend payload.

Always price a job before committing the user's credits. Never print a fixed credit number from memory — costs are backend-driven and shift with model, resolution, duration, and batch size.

zencreator_estimate_price#

Calculate exactly how many credits one candidate input will cost, before submitting.

Parameters

Returns — structuredContent:

• tool_name.
• price — best-effort total credits for ONE call with these params.
• raw — verbatim backend response (varies per tool; may include per_unit, units, total_price).

Errors

• Unknown tool_name — error listing valid names.
• params missing a required field, or carrying fields the tool's input_schema doesn't declare — error. The same payload would be rejected by zencreator_create_task; fix it via zencreator_get_tool_schema first.
• Requested model blocked, or trusted-only while the account has is_trusted=false — the same access error submission would give, instead of a misleading price.
• 422 — params do not satisfy the tool's input_schema (including values outside a field's enum); the backend message lists the exact violations.

Example — "How much for one Seedream image?" Ask your agent to estimate the price for by_prompt with your prompt and model: "SEEDREAM_5".

zencreator_compare_prices#

For a given tool and base params, return the credit price for every available model, sorted cheapest-first. One call replaces N zencreator_estimate_price calls. Call this whenever the user wants to spend less — do not guess which model is cheapest, because the ranking shifts with resolution and other params.

Parameters

Returns — structuredContent:

• tool_name.
• count — how many model × resolution rows returned a valid price.
• compared_resolutions[] (optional) — resolutions present in the result (omitted when resolution is irrelevant).
• prices[] — sorted ascending: model, description, price, optional resolution, is_default, trusted_only.
• errors[] (optional) — models that failed or can't produce a requested resolution: model, optional resolution, reason.

Errors

• Returns isError for tools with no known model catalog — use zencreator_estimate_price instead. Only works for tools with a model catalog (e.g. by_prompt, image_editor, by_ref, faceswap, videogen, lipsync, text_to_video).

Example — "Make my video cheaper." Ask your agent to compare prices for videogen with your prompt and duration but no resolution; it sweeps every resolution and ranks them cheapest-first. Dropping resolution is often the biggest saving — surface it.

Task lifecycle#

zencreator_create_task#

Submit one or more generation calls as a single task. Returns immediately with a task id; generation runs asynchronously.

Not idempotent. Calling it twice creates two tasks and charges credits twice. Confirm with the user before resubmitting on errors. Always zencreator_estimate_price first and state the cost.

Parameters

Returns — structuredContent:

• id — task UUID; pass to zencreator_get_task.
• unique_name, tool_name.
• status — created | processing | partial | completed | failed.
• total — total calls; done — completed so far.
• created_at, comment.

Errors

• 402 — insufficient credits. The error result carries a structured out_of_credits signal (error_code: "insufficient_credits", purchase_url, message); relay it verbatim and have the user top up at app.zencreator.pro/billing.
• 422 — an input element does not satisfy the tool's input_schema. This tool also rejects a submission that omits resolution on a resolution-priced tool (e.g. videogen) rather than letting the backend pick a silent default.
• 429 — rate-limited. Back off.

Example — "Generate 4 variations of this scene." Ask your agent to submit one task with 4 entries in inputs (one task, N calls — never N tasks).

zencreator_run_and_wait#

Submit a task and block until it reaches a terminal status (completed, failed, partial), then auto-fetch each completed call's lazy output and extract asset ids. Collapses create → poll → get-result into one call. Best for images you want in the same turn.

Not idempotent — every successful submission charges credits. Not for video. videogen, video2video, lipsync, and video_upscaler routinely take 60-180 s, longer than most MCP client transport timeouts. The transport hangs up before this tool returns, leaving no task id to resume. Submit videos with zencreator_create_task and poll with zencreator_get_task on the next turn.

Parameters

Returns — structuredContent:

• task_id — resume polling with zencreator_get_task if it timed out.
• tool_name, status, total, done.
• timed_out — true if the wall-clock cap hit before terminal status; the task is still running on the backend.
• duration_ms, polls.
• calls[] — each: call_id, status, output (already fetched for completed calls), error (null unless failed), asset_ids.
• asset_ids — flat union across all completed calls.
• created_at, finished_at, comment.

Errors

• 402 (create phase) — insufficient credits; same structured out_of_credits signal as create_task.
• 422 (create phase) — an input does not satisfy the tool's input_schema.
• 429 — rate-limited. Back off.
• On timeout it returns cleanly with timed_out: true and the live task_id. Do not call this tool again with the same inputs — resume via zencreator_get_task (re-calling creates a new task and charges again).

zencreator_get_task#

Fetch the full state of a single task — status, progress, inputs, and per-call entries.

Parameters

Returns — structuredContent:

• id, unique_name, tool_name, status, total, done, inputs.
• calls[] — each: id, status, output (lazy — usually null here; fetch with zencreator_get_call_result once status="completed"), error (null unless the call failed).
• created_at, finished_at, comment, owner_id.

Errors

• 403 — the task belongs to a different user.
• 404 — task_id not recognised or the task was deleted.

Polling guidance: tasks typically complete in 5-60 seconds; wait at least 2s between polls. status="partial" means some calls finished — you can already fetch those assets. status="failed" is terminal; read calls[].error and do not retry without user confirmation.

zencreator_get_call_result#

Return the structured output of one call. This is the only way to discover the asset ids produced by a completed generation — the task's own calls[].output is intentionally lazy and comes back null.

Parameters

Returns — structuredContent:

• call_id.
• output — tool-specific, verbatim from the backend.
• asset_ids — best-effort extraction of asset UUIDs from common output keys (e.g. image_assets for image tools; video_asset / asset_id for video). If extraction returns empty, inspect output directly.

Errors

• 404 — call_id not found or not owned by the user. List the parent task first.

Hand the returned asset_ids to the asset tools for preview or download URLs.

zencreator_list_tasks#

Return a paginated list of the user's tasks, optionally filtered by tool, status, or free-text search over the comment field.

Parameters

Returns — structuredContent (the canonical paginated envelope):

• total, count, offset.
• items[] — each: id, unique_name, tool_name, status, total, done, created_at, finished_at, comment.
• has_more, next_offset (present when there are more items).

To page, pass next_offset back as offset. Use offsets that are multiples of limit for predictable boundaries.

Errors

• Standard transport / auth errors only.

zencreator_get_processing_tasks#

Return, per tool, whether the user has at least one task currently in flight — a cheap "are any of my generations still running?" check.

Parameters

Returns — structuredContent:

• tools[] — each: tool_name, processing (boolean).
• any_processing — boolean.

Errors

• Standard transport / auth errors only.

zencreator_delete_task#

Soft-delete a task and its associated generations. The user will no longer see it in their task list.

Destructive. Deleted tasks cannot be retrieved through normal endpoints. Always confirm with the user before calling.

Parameters

Returns — structuredContent:

• deleted_task_id.

Errors

• 404 — task_id not found or not owned by the current user.

Prompt helpers (optional)#

These two tools are present only when the prompt-agent sidecar is configured. They may not be available on every deployment. Neither spends ZenCreator credits — they call an external LLM; credits are spent only when you submit the resulting prompt via zencreator_create_task / zencreator_run_and_wait.

zencreator_craft_prompt#

Delegate prompt-writing to a dedicated uncensored LLM that knows the model-specific conventions for ZenCreator's image / video models. Returns a fully-formed prompt ready to drop into the generation's positive_prompt (or equivalent) field. The orchestrator pipes the user's brief through; it does not author the explicit text itself. This project does not use negative prompts.

Parameters

Returns — structuredContent:

• prompts[] — each: prompt (drop verbatim into the generation field), optional rationale.
• model_used — echoes the model you asked for.
• agent_model — which uncensored LLM answered.

Generation settings (aspect ratio, image size, batch size, output format) are not in this output — you set them yourself when calling zencreator_create_task / zencreator_run_and_wait.

Errors

• PROMPT_AGENT_API_KEY not configured — the sidecar is disabled.
• Upstream HTTP error (rate limit, model down) — retry once.
• Agent returned non-JSON — rare transient glitch; retry.

For any NSFW workflow, check zencreator_get_me first: the user needs both nsfw_allowed: true and is_trusted: true, or the downstream generation will refuse and waste credits.

zencreator_describe_asset#

Generate a factual visual description of an asset_id via an uncensored multimodal LLM. Engineered for downstream prompt engineering — identity attributes, state of dress, pose, setting, lighting, camera framing. Descriptions are cached per asset_id in-process (assets are immutable).

Parameters

Returns — structuredContent:

• asset_id.
• description — factual paragraph (~80-200 words).
• media_type — e.g. image/png, image/jpeg.
• cached — true if served from the in-process cache.
• vision_model — which uncensored vision LLM answered.

Errors

• PROMPT_AGENT_API_KEY not configured — the vision agent is disabled.
• Asset is video or audio — the vision model may produce a weak or generic description.
• Vision model upstream error — retry once.

You usually don't need to call this explicitly — zencreator_craft_prompt auto-calls it for any reference passed without a description.

See also#

• Models — the tool_name and model values you pass in.
• Concepts — tasks, calls, assets, credits.
• Asset tools — turn asset ids into preview / download URLs.
• Account tools — credit balance and out_of_credits checks.