# Workflows

End-to-end recipes for driving ZenCreator from your AI client. Each recipe gives the goal, an example natural-language ask you can give your agent, and the ordered MCP-tool chain — naming the **generation tool** (the `tool_name` value) it submits to `zencreator_create_task`.

> **Two layers, kept distinct.** The `zencreator_*` names below are **MCP tools** your client calls. The lowercase names like `by_prompt`, `image_editor`, `videogen` are **generation tools** you pass as the `tool_name` argument *into* `zencreator_create_task`. See [Concepts](./concepts.md) for the full distinction and [Models](./models.md) for the models each generation tool supports.

> **Prices in these examples are illustrative.** Credit cost varies by generation tool, model, resolution, and duration, and is backend-driven. Always call `zencreator_estimate_price` (or `zencreator_compare_prices`) and state the cost before you submit. Never trust a remembered number.

Reference pages used below: [Generation tools](./tools/generation.md) · [Assets](./tools/assets.md) · [Templates](./tools/templates.md) · [Models](./models.md).

---

## 1. Text → image from scratch (`by_prompt`)

**Goal:** Generate a brand-new image from a text prompt.

**Ask your agent:** *"Generate a wide cinematic shot of a neon-lit Tokyo alley at night, photoreal."*

**Tool chain:**

1. `zencreator_list_tools` — confirm `by_prompt` is available and not blocked, and see its models and prices at a glance.
2. `zencreator_get_tool_schema` (for `by_prompt`) — read the input/output JSON Schema, the prompt guide, and per-model guidance. **Call this before submitting** so you build a valid input. Optionally `zencreator_get_model_prompt_guide` for a specific model's prompt tips.
3. `zencreator_estimate_price` — get the exact credit cost of your candidate input. State it to the user before confirming. To shop across models, use `zencreator_compare_prices` (cheapest first; it sweeps resolutions where relevant).
4. **Submit and wait.** For a single image this turn, `zencreator_run_and_wait` is best: it submits *and* blocks until the task reaches a terminal status, then auto-fetches outputs and asset ids.
   - Alternatively, the explicit path: `zencreator_create_task` (returns a task id) → poll `zencreator_get_task` until terminal → `zencreator_get_call_result` to fetch the call's full output and asset ids. **`zencreator_get_call_result` is required to discover generated asset ids** — per-call output on `zencreator_get_task` is lazy/null.
5. **Show or download the result.** `zencreator_get_asset_preview_url` returns a web preview (and can attach the image inline so it renders in chat). `zencreator_get_asset_download_url` returns a presigned link to the original. Use the `_urls` (batch) variants for multiple assets.

---

## 2. Edit / composite with a reference (`image_editor`)

**Goal:** Edit, restyle, or composite using one or more reference images. `image_editor` is the main, most flexible image tool.

**Ask your agent:** *"Take this product photo and place the bottle on a marble countertop with soft window light."*

**Tool chain:**

1. `zencreator_upload_asset` — upload each reference image (from a URL or base64). Returns an `asset_id` you pass into the generation input.
2. `zencreator_get_tool_schema` (for `image_editor`) — see how to wire the reference `asset_id`(s) and prompt into the input, plus model guidance.
3. `zencreator_estimate_price` — confirm the cost for your chosen model and resolution.
4. `zencreator_create_task` with `tool_name: "image_editor"` — submit. (Image edits are usually fast enough for `zencreator_run_and_wait` if you want it inline.)
5. Fetch the result: `zencreator_get_call_result` for the asset ids, then `zencreator_get_asset_preview_url` / `zencreator_get_asset_download_url`.

> Need a similar image *from* a reference rather than an edit? The legacy `by_ref` generation tool exists, but prefer `image_editor`.

---

## 3. Animate a photo → video (`videogen`)

**Goal:** Turn a still image into a short video (or generate video from text).

**Ask your agent:** *"Animate this portrait — gentle head turn and blinking, 5 seconds."*

**Tool chain:**

1. `zencreator_upload_asset` — upload the source photo → `asset_id`.
2. `zencreator_get_tool_schema` (for `videogen`) — read the input shape (first frame asset, prompt, duration/resolution) and model guidance.
3. `zencreator_estimate_price` — video cost scales with duration and resolution; estimate before submitting.
4. `zencreator_create_task` with `tool_name: "videogen"` — submit and keep the returned task id.
5. **Poll, don't block.** `zencreator_get_task` to check status (or `zencreator_get_processing_tasks` for a cheap "anything still running?"). When terminal, `zencreator_get_call_result` to fetch the video asset id, then `zencreator_get_asset_download_url` / `zencreator_get_asset_preview_url`.

> **Use `zencreator_create_task` + polling for video — not `zencreator_run_and_wait`.** Videos take roughly 60–180s and can exceed your client's transport timeout if you block on them. `run_and_wait` is for images.

---

## 4. Use a template / preset

**Goal:** Start from a ready-made preset instead of authoring an input by hand. (A template is also called a preset.)

**Ask your agent:** *"Find a cyberpunk portrait template and run it on my uploaded face."*

**Tool chain:**

1. **Find the template.** `zencreator_list_templates` (paginated) to browse, or `zencreator_search_templates` for semantic + keyword search **if your deployment has the search subsystem enabled** (it may not be available on every deployment).
2. `zencreator_get_template` — fetch the full template, including its ready-to-submit input, so you can see exactly what it will run.
3. `zencreator_use_template` — one-shot: fetch the template, merge any overrides you supply (e.g. swap in your own reference `asset_id` or tweak the prompt), and submit in a single call.
4. Fetch the result the usual way: `zencreator_get_call_result` → `zencreator_get_asset_preview_url` / `zencreator_get_asset_download_url`.

> If you uploaded a reference to use in the template, do `zencreator_upload_asset` first and pass the returned `asset_id` as an override.

See [Templates tools](./tools/templates.md) for the full reference.

---

## 5. Quick recipes

All of these follow the same backbone: **`zencreator_get_tool_schema` → `zencreator_estimate_price` → `zencreator_create_task` → `zencreator_get_call_result` → preview/download.** Only the `tool_name` (and which assets you upload) changes.

| Goal | Generation tool (`tool_name`) | Inputs to prepare |
|---|---|---|
| Swap a face onto a photo (image only) | `faceswap` | Upload the target photo and the face source via `zencreator_upload_asset`. |
| Upscale an image to higher resolution | `upscaler` | Upload (or reuse) the source image `asset_id`. |
| Talking-head lip-sync | `lipsync` | Upload audio + a first-frame image; produces a talking head. |
| Text → video | `text_to_video` | A text prompt only (no source image needed). **Trusted-only tool** — needs `is_trusted`. |
| Stitch 2–5 clips into one video | `video_merger` | Upload each clip via `zencreator_upload_asset`; pass them as `clips[]` (each with its `source_duration_sec`, optional trims), plus `transition` / `fps`. The final assembly step after generating clips with `videogen` / `text_to_video`. |

Reminders:

- **Face-swap and upscaler are image-only** — for video, use `video2video` (replace a character in a video) or `video_upscaler` instead.
- **`lipsync`, `text_to_video`, and any video output take 60–180s** — submit with `zencreator_create_task` and poll `zencreator_get_task`, don't `run_and_wait`.
- Always `zencreator_estimate_price` first; cost varies by model, resolution, and (for video) duration.

See [Generation tools](./tools/generation.md) for every `tool_name` and [Models](./models.md) for the models each one supports.

---

## 6. NSFW workflow

ZenCreator supports uncensored / NSFW generation, gated by two account flags. Be frank but factual.

**Goal:** Generate adult content with an appropriate model.

**Ask your agent:** *"I want to generate NSFW content — check my account is set up for it, then make this image."*

**Tool chain:**

1. `zencreator_get_me` — check `nsfw_allowed` and `is_trusted`.
   - **`nsfw_allowed` must be `true`.** If it's `false`, the fix is: enable adult content in your ZenCreator account settings, then retry.
   - **`is_trusted`** (Trusted Status) is required for trusted-only models — marked **(trusted)** in the model lists — and for the trusted-only tools `male_undresser`, `flux_klein_lora`, `text_to_video`. Trusted Status is granted automatically after your first payment (any credit pack) and is permanent.
2. *(Optional)* `zencreator_craft_prompt` — delegate authoring of the explicit, model-specific prompt to an uncensored sidecar LLM. This exists precisely so an orchestrator that won't write explicit prompts itself can still drive NSFW workflows. It spends **no** ZenCreator credits. *(Available only when the prompt-agent sidecar is configured on your deployment.)*
3. **Pick a model.** Choose an NSFW-capable (and, if needed, trusted) model for your generation tool — for example `SDXL_NSFW`, `FLUX_KLEIN_NSFW`, or `wan@2.7-nsfw`. The `undress` / `male_undresser` generation tools (built on the Flux Klein LoRA) are purpose-built for removing clothing. See [Models](./models.md) for the full list and which are **(trusted)**.
4. `zencreator_get_tool_schema` + `zencreator_estimate_price` — validate the input and confirm cost.
5. `zencreator_create_task` (or `zencreator_run_and_wait` for images) → `zencreator_get_call_result` → preview/download.

---

## Credits and running out

Generation spends credits. Before you commit, call `zencreator_estimate_price` (or `zencreator_compare_prices` to shop models) and state the cost to the user.

If you run out mid-flight, generation returns HTTP **402** with a structured signal:

```json
{ "error_code": "insufficient_credits", "out_of_credits": true, "purchase_url": "...", "message": "..." }
```

The same `out_of_credits` + `purchase_url` also appear in `zencreator_get_me`, so "out of credits" reads identically whether you check ahead or hit it mid-generation. Top up at **https://app.zencreator.pro/billing**.

---

## See also

- [Generation tools reference](./tools/generation.md)
- [Assets tools reference](./tools/assets.md)
- [Templates tools reference](./tools/templates.md)
- [Generation tools & models](./models.md)
- [Concepts](./concepts.md) · [Troubleshooting](./troubleshooting.md)