Tool reference

create_media — the front door

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

{
  "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 outputs, each billed
`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; same key + body never double-bills

What quality does underneath: for images it biases the auto-router (fast → speed, best → quality); for options it picks the model spread and the default budget (12¢ / 30¢ / 45¢ when max_spend_cents is omitted, always clamped to 5–100¢); for video it picks google-veo-3-fast / auto / veo-3.1.

Continuity — say it like a person

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

`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.

“Give me 4 directions for the game world.”

“Now a courier character in the style of the second one.”

Courier character matching direction 2's style — One call: generate_image with source: "2". Same world, new character.

Creative memory — survives sessions

Name a keeper once, reuse it forever:

{ "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. 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

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

{ "url": "https://cdn...", "filename": "espresso-hero-1.webp", "mime": "image/webp" }

All 18 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, 2–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
`add_credits`	free	Mint a Stripe Checkout link for $25 / $100 / $250 (never enables auto-reload)

Every tool answers with 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. Nothing is charged either way.

Specialist parameters

generate_image / edit_image

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: `speed` steers to `nano-banana`, `quality` to `nano-banana-pro`
`max_spend_cents`	—	Integer 1–2000; returns `budget_too_low` instead of exceeding it
`idempotency_key`	—	≤128 chars; same key + body never double-bills

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.

generate_video / image_to_video

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
`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`	Audio track — honored by `seedance-2` and `kling-video`; other models ignore it
`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`; works on `seedance-pro` (what `auto` picks for it) or `kling-2.5-turbo`, `invalid_model` on anything else

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.

compare_models

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.

get_generation_status

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 / get_creation

search_creations:

Parameter	Default	Description
`kind`	`all`	`image` · `video` · `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 / list_creative_entities

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 / estimate_cost

search_models:

Parameter	Default	Description
`kind`	—	`image` or `video`
`query`	—	Free-text match on name and strengths (≤200 chars)
`max_price_cents`	—	Integer ≥1 — only models at or under this per-output price
`needs_references`	—	`true` → only image models that accept reference images

Each result carries 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`
`prompt`	—	Needed when `model` is `auto` (≤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

The estimate also reports within_balance and within_spend_limit.

upload_asset

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 the permanent public_url to pass as a reference.

prepare_scrub_video / publish_page

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 / get_account_balance

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.

Get Started

Using It

Reference

create_media — the front door

Continuity — say it like a person

Creative memory — survives sessions

Ship-ready outputs

All 18 tools

Specialist parameters

​create_media — the front door

​Continuity — say it like a person

​Creative memory — survives sessions

​Ship-ready outputs

​All 18 tools

​Specialist parameters

create_media — the front door

Continuity — say it like a person

Creative memory — survives sessions

Ship-ready outputs

All 18 tools

Specialist parameters