> ## 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

> One front-door tool does almost everything. Sixteen specialists for fine control.

## create\_media — the front door

Say what you want. NinjaChat classifies it (make / edit / animate / options), picks the model, and stays inside your budget.

```json theme={null}
{
  "brief": "hero shot of a matte-black espresso machine, dramatic light",
  "quality": "balanced",
  "aspect_ratio": "16:9"
}
```

| Parameter         | Default    | Description                                                 |
| ----------------- | ---------- | ----------------------------------------------------------- |
| `brief`           | —          | What you want, in plain language                            |
| `quality`         | `balanced` | `fast` · `balanced` · `best` — no model names needed        |
| `aspect_ratio`    | `1:1`      | `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3`                 |
| `max_spend_cents` | —          | Hard budget. With `quality: "best"`: best possible under it |
| `action`          | `auto`     | Force `make` / `edit` / `animate` / `options`               |
| `source`          | —          | Continue from a previous result ↓                           |
| `use`             | —          | Apply saved characters/products/styles ↓                    |

## Continuity — say it like a person

The server remembers recent results, so nobody re-pastes URLs:

| `source`        | Means                                  |
| --------------- | -------------------------------------- |
| `"last"`        | The newest output                      |
| `"2"`           | Pick #2 from the last numbered gallery |
| a generation ID | Any past creation                      |

> "Give me 4 directions for the game world."

<Columns cols={4}>
  <Frame>
    <img src="https://cdn.photogenius.ai/new-ai-images/mcp-landing/v1/worlds/loam-1.webp" alt="Game world direction 1" />
  </Frame>

  <Frame>
    <img src="https://cdn.photogenius.ai/new-ai-images/mcp-landing/v1/worlds/loam-2.webp" alt="Game world direction 2" />
  </Frame>

  <Frame>
    <img src="https://cdn.photogenius.ai/new-ai-images/mcp-landing/v1/worlds/loam-3.webp" alt="Game world direction 3" />
  </Frame>

  <Frame>
    <img src="https://cdn.photogenius.ai/new-ai-images/mcp-landing/v1/worlds/loam-4.webp" alt="Game world direction 4" />
  </Frame>
</Columns>

> "Now a courier character in the style of the second one."

<Frame caption="One call: generate_image with source: &#x22;2&#x22;. Same world, new character.">
  <img src="https://cdn.photogenius.ai/new-ai-images/mcp-landing/v1/worlds/loam-character.webp" alt="Courier character matching direction 2's style" />
</Frame>

## Creative memory — survives sessions

Name a keeper once, reuse it forever:

```json theme={null}
{ "tool": "save_creation_as", "name": "Maya", "type": "character", "source": "2" }
```

Then `use: ["Maya"]` on any creation tool applies her reference images automatically. Types: `project` · `character` · `product` · `style`. Forgot the name? `list_creative_entities`.

## Ship-ready outputs

Every image returns three fields — download, commit, done:

```json theme={null}
{ "url": "https://cdn...", "filename": "espresso-hero-1.webp", "mime": "image/webp" }
```

## All 17 tools

| Tool                     | Cost   | One-liner                                                                                       |
| ------------------------ | ------ | ----------------------------------------------------------------------------------------------- |
| `create_media`           | billed | Anything media — the default                                                                    |
| `generate_image`         | billed | Images with a specific model                                                                    |
| `edit_image`             | billed | Recolor, restyle, inpaint                                                                       |
| `generate_video`         | billed | Text → video                                                                                    |
| `image_to_video`         | billed | Still → motion                                                                                  |
| `compare_models`         | billed | One prompt, up to 6 models, strict budget                                                       |
| `upload_asset`           | free   | Push a local file up for edits/video                                                            |
| `save_creation_as`       | free   | Name a keeper                                                                                   |
| `list_creative_entities` | free   | List saved names                                                                                |
| `search_creations`       | free   | Search everything ever made                                                                     |
| `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                                                                        |

## Specialist parameters

<AccordionGroup>
  <Accordion title="generate_image / edit_image">
    | Parameter              | Default    | Description                          |
    | ---------------------- | ---------- | ------------------------------------ |
    | `prompt`               | —          | Max 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           |
    | `source` / `use`       | —          | Continuity + saved entities          |
    | `quality_vs_speed`     | `balanced` | Biases `auto` routing                |
    | `max_spend_cents`      | —          | Errors instead of exceeding          |
    | `idempotency_key`      | —          | Same key + body never double-bills   |
  </Accordion>

  <Accordion title="generate_video / image_to_video">
    | Parameter              | Default | Description                                  |
    | ---------------------- | ------- | -------------------------------------------- |
    | `prompt`               | —       | What the video shows                         |
    | `model`                | `auto`  | Video slug or `auto`                         |
    | `duration`             | `8`     | 4–15 seconds                                 |
    | `aspect_ratio`         | `16:9`  | `16:9` or `9:16`                             |
    | `generate_audio`       | `false` | Audio track (Seedance)                       |
    | `image_url` / `source` | —       | `image_to_video` only — the still to animate |
    | `max_spend_cents`      | —       | Hard ceiling                                 |

    Video is async: the call returns a job, the agent polls `get_generation_status` (\~15s apart), clips render in 1–2 minutes. Failures refund automatically.
  </Accordion>

  <Accordion title="compare_models">
    | Parameter            | Description                                  |
    | -------------------- | -------------------------------------------- |
    | `prompt`             | The prompt to race                           |
    | `models`             | Up to 6 slugs — omit for an automatic spread |
    | `total_budget_cents` | Strict cap across the whole bakeoff          |

    Results come back numbered in pick order — choose one and continue from it with `source`.
  </Accordion>
</AccordionGroup>