> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ninjachat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Tool reference
> Image, video and voice tools, saved references, cost estimates and publishing.
## create\_media
Use `create_media` for images and video. Use `generate_speech` for [voiceovers](/mcp/voiceovers). To approve an exact model and price, quote the corresponding specialist tool with `estimate_cost` and generate with the same parameters.
```json theme={null}
{
"brief": "hero shot of a matte-black espresso machine, dramatic light",
"quality": "balanced",
"aspect_ratio": "16:9"
}
```
| Parameter | Default | Description |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `brief` | — | **Required.** What you want, in plain language (1–4,000 chars) |
| `quality` | `fast` | `fast` · `balanced` · `best` — no model names needed. `fast` keeps the first picture cheap and immediate |
| `aspect_ratio` | `1:1` | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3` — video collapses to `16:9` or `9:16` |
| `count` | `1` | 1–4 images or requested comparison entries; video returns one job per call |
| `max_spend_cents` | — | Hard budget, integer 1–2000. With `quality: "best"`: the best model that fits under it |
| `action` | `auto` | Force `make` / `edit` / `animate` / `options` |
| `source` | — | Continue from a previous result ↓ (≤200 chars) |
| `reference_image_urls` | — | Up to 14 public HTTPS URLs. Text-to-video keeps the first 4; `animate` uses only the `source` |
| `use` | — | Up to 3 saved characters/products/styles ↓ |
| `duration` | `8` | 4–15 seconds — video only |
| `idempotency_key` | — | ≤128 chars; reuse unchanged on retry within the replay window |
## Continuity — say it like a person
Continue from recent image results with `source`:
| `source` | Means |
| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `"last"` (also `"latest"`, `"it"`, `"this"`) | The newest output |
| `"2"` | Pick #2 from the last numbered gallery |
| a generation ID (`img_…`, `cmp_…`, `vid_…`) | Any past creation — older than the recent window, it's looked up in your durable history |
| an `https://` URL | Passed through as-is |
Recents are kept per user **and** per client for 24 hours — a Cursor session doesn't see what Claude Code made an hour ago, but generation IDs always resolve.
## Creative memory — survives sessions
Call `save_creation_as` with an approved image reference:
```json theme={null}
{ "name": "Maya", "type": "character", "source": "2" }
```
Then `use: ["Maya"]` on image and video generation tools applies her saved image references. Speech and model comparisons do not accept `use`. Types: `project` · `character` · `product` · `style`. Saving the same name again adds another reference (each name keeps up to 8; the oldest rotates out). Forgot the name? `list_creative_entities`.
## Ship-ready outputs
Image outputs include a URL, suggested filename and MIME type. An agent with filesystem access can download and verify them:
```json theme={null}
{ "url": "https://cdn...", "filename": "espresso-hero-1.webp", "mime": "image/webp" }
```
## All 19 tools
| Tool | Cost | One-liner |
| ------------------------ | ------ | ----------------------------------------------------------------------------------------------- |
| `create_media` | billed | Generate or edit images and create video |
| `generate_speech` | billed | Narration and voiceovers as MP3 or WAV |
| `generate_image` | billed | Images with a specific model |
| `edit_image` | billed | Edit an image with a text instruction |
| `generate_video` | billed | Text → video |
| `image_to_video` | billed | Still → motion |
| `compare_models` | billed | One prompt, 2–6 models, strict budget |
| `upload_asset` | free | Get an upload URL for a reference file |
| `save_creation_as` | free | Name a keeper |
| `list_creative_entities` | free | List saved names |
| `search_creations` | free | Search saved image, video and audio history |
| `get_creation` | free | One past creation, full metadata |
| `get_generation_status` | free | Poll a video job |
| `search_models` | free | Find models by task/style/price |
| `estimate_cost` | free | Exact price before running |
| `prepare_scrub_video` | free | Turn a finished video into a scroll-cinema kit — scrub-optimized MP4s, posters, boundary frames |
| `publish_page` | free | Publish a complete HTML page live to your ninja.site subdomain |
| `get_account_balance` | free | Balance + limit headroom |
| `add_credits` | free | Mint a Stripe Checkout link for \$25 / \$100 / \$250 (never enables auto-reload) |
Tool results include structured JSON — `{ "ok": true, … }` or `{ "ok": false, "error": { "code", "message", "recoverable", "next_steps", … } }` — so the agent can read and recover from the payload. The one exception is argument validation: a missing or out-of-range parameter is rejected before the tool runs, as a plain-text result flagged `isError: true` (`Input validation error: Invalid arguments for tool …`) rather than the JSON envelope. Invalid arguments are not charged.
## Specialist parameters
Required: `input` (1–4,096 characters) and `idempotency_key` (1–128 characters). Defaults: `model: "tts-1-hd"`, `voice: "nova"`, `response_format: "mp3"`, `speed: 1`. Supports MP3 or WAV, nine voices and speed 0.25–4. `max_spend_cents` accepts fractional cents, greater than 0 and at most 100.
See [Voiceovers](/mcp/voiceovers) for all voices and quote/generation examples.
| Parameter | Default | Description |
| ---------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | — | **Required.** 1–4,000 chars |
| `model` | `auto` | Slug from `search_models`, or `auto` |
| `n` | `1` | 1–4 outputs, each billed |
| `aspect_ratio` | `1:1` | Same enum as `create_media` |
| `reference_image_urls` | — | Up to 14 public HTTPS URLs. Each model's own ceiling is `max_references` in `search_models` — past it you get `too_many_references` |
| `source` | — | Continuity (≤200 chars). `edit_image` needs a `source`, a reference URL, or a `use` entity |
| `use` | — | Up to 3 saved entities |
| `quality_vs_speed` | `balanced` | `quality` · `balanced` · `speed` — biases `auto` only: the router selects a compatible model for the task |
| `max_spend_cents` | — | Integer 1–2000; returns `budget_too_low` instead of exceeding it |
| `idempotency_key` | — | ≤128 chars; reuse unchanged on retry within the replay window |
An explicit `model` is a contract — no silent substitution. `auto` may reroute to a compatible model if a provider fails, and the charge settles on the model that ran. Edit-only models (`runway-gen4-image-turbo`, `qwen-image-edit-plus`) return `model_requires_reference` without a reference.
| Parameter | Default | Description |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | — | **Required.** What the video shows (1–4,000 chars) |
| `model` | `auto` | Video slug or `auto` |
| `duration` | `8` | 4–15 seconds — billed on each model's own curve, see [Billing](/mcp/billing) |
| `aspect_ratio` | `16:9` | `16:9` or `9:16` |
| `reference_image_urls` | — | Up to 4 public HTTPS URLs for subject/style consistency |
| `use` | — | Up to 3 saved entities (they share the 4-reference ceiling) |
| `generate_audio` | `false` | Request model-generated audio where supported; use `generate_speech` for a separate scripted voiceover |
| `max_spend_cents` | — | Integer 1–2000 |
| `idempotency_key` | — | ≤128 chars |
| `image_url` | — | `image_to_video` only — public HTTPS URL of the still to animate |
| `source` | — | `image_to_video` only — animate a previous result instead of passing `image_url` |
| `end_image_url` | — | `image_to_video` only — lock the final frame. Requires `image_url`; use `seedance-pro` in the MCP catalog; `auto` selects it when a final frame is supplied |
Video is async: the call returns a `generation_id` and `eta_seconds`, and the agent polls `get_generation_status` (\~15s apart). Render time depends on the model — from 20–90 seconds on `seedance-lite` to 2–6 minutes on `kling-video`; `search_models` lists each model's `eta_seconds`. Failures refund automatically.
Revise a finished clip in place instead of re-rolling it. Both default to the newest video.
| Parameter | Default | Description |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instruction` | — | **Required.** `edit_video`: what to change ("make the boat blue"); everything else, including the length, stays as it was. `extend_video`: what happens next; the new footage continues from the last frame |
| `source` | `last` | The clip to revise: `last`, an output number, or a `generation_id` |
| `seconds` | `4` | `extend_video` only — seconds to add (3–10); a clip can grow to 40 seconds in total |
| `max_spend_cents` | — | Integer 1–2000 |
| `idempotency_key` | — | ≤128 chars |
Only clips made with `gemini-omni-flash` (the fast default) can be revised; on any other clip the tool explains this and suggests generating on that model first. Same async flow as `generate_video`: a `generation_id` comes back, poll `get_generation_status`, and the whole revised or lengthened clip is delivered. `create_media` routes an `edit` on a video source here automatically ("keep going" lengthens). Pricing: an edit re-renders the clip; an extension bills only the added seconds — both plus the clip carried as context. `estimate_cost` quotes either with `source`.
| Parameter | Default | Description |
| -------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | — | **Required.** The prompt to race (1–4,000 chars) |
| `models` | `z-image-turbo` `nano-banana-2` `seedream` `gpt-image-2` | 2–6 image slugs. Edit-only models are rejected |
| `total_budget_cents` | — | **Required.** Integer 5–100. Models are added cheapest-first until the budget is spent; the rest come back as `skipped`. Fewer than two fit → `budget_too_low` |
| `aspect_ratio` | `1:1` | Same enum as `create_media` |
| `idempotency_key` | — | ≤128 chars |
Results come back numbered in pick order — choose one and continue from it with `source`. A model that fails inside the bakeoff costs nothing; you're charged for the ones that delivered.
| Parameter | Default | Description |
| --------------- | ------- | --------------------------------------------------------------------- |
| `generation_id` | — | **Required.** The `vid_…` id from `generate_video` / `image_to_video` |
Returns `pending` (with `progress_percent` and `eta_seconds`), `succeeded` (with the playable URL), or a refunded failure. Images finish synchronously and never need polling.
`search_creations`:
| Parameter | Default | Description |
| --------- | ------- | ------------------------------------------------ |
| `kind` | `all` | `image` · `video` · `audio` · `all` |
| `query` | — | Substring match on prompt and model (≤200 chars) |
| `limit` | `20` | 1–50 |
`get_creation`:
| Parameter | Default | Description |
| --------------- | ------- | -------------------------------------------------------------------------- |
| `generation_id` | — | **Required.** Any id from a generation or `search_creations` (1–200 chars) |
`save_creation_as`:
| Parameter | Default | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name` | — | **Required.** 1–80 chars — the name you'll reuse |
| `type` | — | **Required.** `project` · `character` · `product` · `style` |
| `source` | `last` | Which image to save: `last`, an output number, or a generation id. Videos can't be saved — save the still they came from |
| `description` | — | Optional note (≤500 chars) |
`list_creative_entities`:
| Parameter | Default | Description |
| --------- | ------- | ---------------------------------- |
| `type` | — | Optional filter to one entity type |
`search_models`:
| Parameter | Default | Description |
| ------------------ | ------- | -------------------------------------------------------------------------------------------------- |
| `kind` | — | `image`, `video` or `audio` |
| `query` | — | Free-text match on name and strengths (≤200 chars) |
| `max_price_cents` | — | Integer ≥1 — filter by per-image price, video starting price, or speech price per 1,000 characters |
| `needs_references` | — | `true` → only image models that accept reference images |
Image and video results carry `price_cents` (image: per output; video: the 4-second "from" price). Video results also carry `price_cents_at_default_duration` and `default_duration_seconds` (8) — the amount you are billed when you accept the tool defaults — plus `eta_seconds`.
`estimate_cost`:
| Parameter | Default | Description |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `tool` | — | **Required.** `generate_image` · `edit_image` · `generate_video` · `image_to_video` · `compare_models` · `generate_speech` |
| `input` | — | Exact speech script for `generate_speech` (1–4,096 chars) |
| `prompt` | — | Needed for automatic image/video model selection (≤4,000 chars) |
| `model` | `auto` | Slug or `auto` — the response names the model `auto` would pick, and why |
| `n` | `1` | 1–4 |
| `duration` | `8` | 4–15 seconds — video tools |
| `models` | — | `compare_models` only, up to 6 |
| `total_budget_cents` | — | `compare_models` only (assumes 25 when omitted) |
| `has_references` | `false` | Tells the router a reference image will be attached |
Audio model results include `price_cents_per_1000_characters`, voices and formats. Speech estimates default to `tts-1-hd` when the model is `auto`. The estimate also reports `within_balance` and `within_spend_limit`; API-key budgets are rechecked during generation.
| Parameter | Default | Description |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `content_type` | — | **Required.** `image/png` · `image/jpeg` · `image/webp` · `video/mp4` · `audio/mpeg` · `audio/wav` |
| `size_bytes` | — | **Required.** Exact byte count — the signed URL rejects any other `Content-Length`. Caps: images 25 MiB, MP4 100 MiB, audio 30 MiB |
| `file_name` | — | For your own bookkeeping (≤200 chars); the storage key is server-chosen |
Returns `upload_url` (HTTP PUT, valid for 10 minutes) and `public_url`. The agent must PUT the actual file bytes with the declared content type and length before using `public_url`. A chat attachment is usable only if the agent can access and upload its bytes.
`prepare_scrub_video` — pass one of:
| Parameter | Default | Description |
| --------------- | ------- | --------------------------------------------------------------------------- |
| `generation_id` | — | A **completed** `vid_…` generation (`generation_pending` until it is) |
| `video_url` | — | A NinjaChat generation URL or an `upload_asset` `public_url` (≤2,000 chars) |
`publish_page`:
| Parameter | Default | Description |
| --------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `title` | — | **Required.** 1–120 chars |
| `html` | — | **Required.** Complete self-contained document, up to 400,000 chars |
| `slug` | — | 3–32 chars (`a-z`, `0-9`, hyphens). Reuse a slug you own to update that page in place; omit for a generated name |
| `site_username` | — | Claim a ninja.site handle on first publish (3–20 chars). Ignored once the account has one — handles are permanent |
`add_credits`:
| Parameter | Default | Description |
| ------------ | ------- | ----------------------------------------------- |
| `amount_usd` | `25` | `25` · `100` · `250` — nothing else is accepted |
Returns a Stripe `checkout_url` for the user to open. It never turns auto-reload on.
`get_account_balance` takes no parameters and returns the balance, what it buys, this month's spend against your limit, and the subscriber allowance state.