Tool reference

create_media

Use create_media for images and video. Use generate_speech for voiceovers. To approve an exact model and price, quote the corresponding specialist tool with estimate_cost and generate with the same parameters.

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

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

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

generate_speech

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 for all voices and quote/generation examples.

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

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

edit_video / extend_video

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.

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` · `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 / 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`, `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.

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

Continuity — say it like a person

Creative memory — survives sessions

Ship-ready outputs

All 19 tools

Specialist parameters

​create_media

​Continuity — say it like a person

​Creative memory — survives sessions

​Ship-ready outputs

​All 19 tools

​Specialist parameters

create_media

Continuity — say it like a person

Creative memory — survives sessions

Ship-ready outputs

All 19 tools

Specialist parameters