Docs/Tools
Tools
Nine tools. Every parameter.
Exactly what tools/list returns on the hosted connector, rendered from the same schemas the server validates with. If this page and tools/list ever disagree, tools/list wins and our CI is red.
On this page
Three spend credits and return a job id. Six are free. Poll get_run_status until a job is completed; never report a result before you hold the URL.
generate_video has three modes and the fields you pass pick one: first_frame (and optional last_frame) selects image-to-video; refs, video_refs or audio_refs select reference; neither is text. Frames and refs cannot be mixed on Seedance. quality (480p, 720p, 1080p, default 720p) sets the price per second.
generate_videospends creditsGenerate Video
Render a video clip from YOUR prompt on the model YOU choose, in one of three MODES that follow from the fields you pass: TEXT (prompt only), IMAGE-TO-VIDEO (`first_frame`: an https still that becomes frame one, optionally `last_frame` to end on; the clip animates the still) or REFERENCE (`refs`: https images such as a portrait, a character sheet from list_characters or a product photo whose identity/look is kept; `video_refs`: clips whose motion or framing is followed; `audio_refs`: a voice or sound to carry; address them in the prompt as @image1, @video1, @audio1). Frames and refs cannot be mixed. Write the shot like a director: who is in frame, where, what happens, camera, and the exact spoken words in quotes if anyone talks. Models: seedance-2.0, seedance-2.5 (default seedance-2.0; call list_models for each model's modes, limits, prices and recent results; or pass model:"auto"). Aspect: 9:16 default, also 16:9, 1:1, 4:3, 3:4, 21:9, adaptive. Quality: 480p, 720p (default), 1080p; the price per second follows the quality (seedance-2.0: 30 credits/s at 480p, 60 credits/s at 720p, 150 credits/s at 1080p). Reference clip seconds are billed like output seconds. Call `quote` first if the user cares about cost. Returns a job id, then call get_run_status until it is done and hand the user the URL. IMAGES: pass an https URL. If you only have raw bytes or a data: URL, call `upload_image` FIRST and pass the URL it returns. Never paste base64 into these arguments, the client prints tool arguments in the conversation, so a base64 image becomes a wall of text for the user and is re-sent on every retry.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| prompt● | string | 3 to 4000 chars | – | The shot, as a director would say it: who (age, look), where (setting, light), what happens, camera (phone framing), and, if anyone speaks, the exact words in quotes. About 2.3 words per second. With references, address them as @image1, @video1, @audio1. |
| model | string | – | – | A live video model id from list_models, or "auto" to let agent-media pick from recent results. Omit for the default. Call list_models for what each model is good for, its modes, limits and price. |
| first_frame | string | https url | – | IMAGE-TO-VIDEO: an https image that becomes frame one of the clip (a still you want animated, a product shot, a portrait). Cannot be combined with refs, video_refs or audio_refs on Seedance. |
| last_frame | string | https url | – | Optional with first_frame: the image the clip ends on; the model animates from first to last. |
| refs | string[] | up to 30, https url | – | REFERENCE-TO-VIDEO: image references (https URLs): a portrait, a character sheet from list_characters, a product photo. The model keeps that identity/look. Address them in the prompt as @image1, @image2... |
| video_refs | string[] | up to 10, https url | – | Reference clips (https mp4/mov) whose motion, framing or look the model should follow; @video1... in the prompt. Their seconds are billed like output seconds. |
| audio_refs | string[] | up to 10, https url | – | Reference audio (https wav/mp3): a voice or a sound the clip should carry; @audio1... in the prompt. |
| seconds | integer | 1 to 60 | 5 | Clip length in seconds (the model sets the range; seedance: 4 to 15). Credits = seconds x the per-second rate at the chosen quality. |
| aspect | string | 9:1616:91:14:33:421:9adaptive | – | 9:16 (default for text and reference), 16:9, 1:1, 4:3, 3:4, 21:9, or adaptive (follows the first frame or reference; the default and the only option in image mode on seedance-2.5). |
| quality | string | 480p720p1080p | "720p" | 480p (cheapest), 720p (default), 1080p (dearest). Price per second differs; see list_models. |
| audio | boolean | – | true | Render native audio (speech from the quoted words, ambience). false = silent clip. |
| seed | integer | 0 to 2147483647 | – | Only for models whose mode lists seed support (none of the live Seedance modes). Refused elsewhere. |
● required
generate_imagespends creditsGenerate Image
Render one image from YOUR prompt. Without refs it paints from the prompt; with refs (https URLs) it edits/composes from them, a portrait to re-light, a product to place in a hand, a character sheet to pose. Use it to build the reference a video needs (portrait first, then generate_video with that URL in refs). Models: gpt-image-2.5, gpt-image-2.5-flare, gpt-image-2 (default gpt-image-2.5). Spends credits per image (see list_models). Returns a job id, poll get_run_status for the image URL. IMAGES: pass an https URL. If you only have raw bytes or a data: URL, call `upload_image` FIRST and pass the URL it returns. Never paste base64 into these arguments, the client prints tool arguments in the conversation, so a base64 image becomes a wall of text for the user and is re-sent on every retry.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| prompt● | string | 3 to 4000 chars | – | What to paint. Be concrete: subject, age, framing, light, lens, mood, what the hands do. |
| model | string | – | – | A live image model id from list_models, or "auto" to let agent-media pick from recent results. Omit for the default (gpt-image-2). |
| refs | string[] | up to 4, https url | – | Reference images (https URLs, up to 4). With refs the model EDITS/composes from them (a product into a hand, a portrait re-lit); without, it paints from the prompt alone. |
| size | string | 1024x10241024x15361536x1024 | "1024x1536" | 1024x1536 portrait (default, for 9:16 video), 1024x1024 square, 1536x1024 landscape. |
● required
generate_audiospends creditsGenerate Audio
Speak text in a named voice (jessica, sarah, liam, chris, lily, bill, matilda, or a raw ElevenLabs voice id). Emotion tags like [excited] or [whispers] are honoured. For a talking-head clip you usually do NOT need this: generate_video renders native speech when the words are in the prompt. Use it for voiceover over b-roll or a standalone audio file. Models: elevenlabs-tts. Spends 1 credit per 100 characters, rounded up. Returns a job id, poll get_run_status for the mp3 URL. The mp3 URL can be passed as an audio_ref to generate_video.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| text● | string | 1 to 4000 chars | – | The words to speak. Emotion tags like [excited] or [whispers] are honoured. Priced per character; see list_models. |
| model | string | – | – | A live audio model id from list_models, or "auto". Omit for the default (elevenlabs-tts). |
| voice | string | – | "sarah" | A voice name: jessica (young female), sarah (female), liam (young male), chris (male), lily (elder female), bill (elder male), matilda (warm), or a raw ElevenLabs voice id. |
| tone | string | energeticcalmconfidentdramatic | – | energetic | calm | confident | dramatic. |
● required
quoteread onlyQuote
Price a generate_image / generate_video / generate_audio call WITHOUT running it. Pass the same `input` you would pass to the tool. Returns credits (1 credit = $0.01), the model that would run, and the breakdown. Costs nothing. Use it before spending when the user asked about cost, when choosing between models, or before a clip longer than a few seconds.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| kind● | string | imagevideoaudio | – | |
| input● | object | – | – | The exact arguments you would pass to generate_<kind>. |
● required
list_charactersread onlyList Characters
List the authenticated user's saved, reusable characters. Each has a character_id (char_…) and a character_sheet_url, pass the character_sheet_url (and/or portrait URL) in `refs` of generate_video / generate_image to reuse that exact identity, or EITHER to make_ugc's `character` prop on the fixed surface. Plus a portrait/thumbnail URL for display.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| limit | integer | 1 to 100 | – | Max characters to return (default 50). |
● required
get_run_statusread onlyGet Run Status
Check a generation you already submitted, and get its output URL (video, image or audio) when it is done. Pass the id ANY agent-media tool returned (run id, skill run id, or job id), this resolves all of them. Set wait:true to block until the job reaches a terminal state (up to ~45 seconds per call; if it is still running, just call again: seedance-2.0 needs about 3 minutes for a 5 s clip, seedance-2.5 12 to 25 minutes, so keep calling until it is done). ALWAYS call this after submitting: without it you cannot tell whether the video succeeded, and cannot give the user a link.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| run_id● | string | – | – | The run_id / skill_run_id / job_id returned when you submitted. |
| wait | boolean | – | – | Block until the run finishes or ~45 seconds elapse (default false). A video needs several such calls; just call again. |
● required
upload_imagefree writeUpload Image
Store an image and get back a stable https URL you can pass to any agent-media tool. Costs NO credits. THREE ways in, in this order: 1. FILE ON DISK (best, and the only one that keeps full resolution): call upload_image with `file_bytes` set to the exact byte size of the file (`wc -c < photo.png`) and `file_name`. You get back a `put_url`; run the printed curl to stream the file straight to storage, then call upload_image again with the `upload_key` you were given to get the URL. The bytes never pass through this conversation, so there is NO reason to resize, crop or re-encode the user’s photo first. Do not: a downscaled product photo is what the video model will show. Up to 25 MB. 2. A URL you already have: pass `image_url` to re-host it. 3. Raw bytes with no shell available: pass `image_base64` (PNG or JPEG, 10 MB max after decoding). Only when 1 and 2 are impossible, and even then upload the original, never a shrunken copy. Then pass the returned URL everywhere. Do NOT paste base64 into other tool arguments or into the conversation: the client displays tool arguments to the user, so a base64 image becomes a wall of unreadable text, and every retry re-sends it.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| file_bytes | integer | – | – | Step 1 of the file path: the exact size of the file in bytes (`wc -c < photo.png`). Returns a put_url and an upload_key. Full resolution, up to 25 MB. |
| file_name | string | – | – | Optional with file_bytes: the file name, so the content type is right (.png or .jpg). |
| upload_key | string | – | – | Step 2 of the file path: the upload_key you were given, after the curl PUT finished. Returns the image_url. |
| image_base64 | string | – | – | The image bytes, base64-encoded. A `data:image/png;base64,...` prefix is accepted and stripped. Last resort: use file_bytes when you can run a shell. |
| image_url | string | – | – | An https URL to fetch and re-host instead. |
● required
list_modelsread onlyList Models
List the generation models agent-media can use: for each, its MODES (video: text, image-to-video via first_frame, reference via refs / video_refs / audio_refs) with the exact inputs, limits, aspects, qualities and credits per second of every mode, a "pick when" line, prompting tips, expected latency, how to select it, plus `recent`: the last 30 days of real runs per model (fail rate, auto-judge score, user ratings, median render time). Read this BEFORE choosing a model or a mode for generate_video / generate_image / generate_audio: the default seedance-2.0 is right for most jobs. Pass the id as `model`, or `model:"auto"` and the printed policy picks from the stats. Costs NO credits. Set include_candidates:true to also see planned models that cannot be selected yet.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| include_candidates | boolean | – | – | Also return planned models (no price, not selectable). Default false. |
● required
rate_runfree writeRate Run
Rate a finished generate_video / generate_image / generate_audio run 1 to 5, with an optional note (what was wrong or right). Costs nothing. Do this when the user reacts to an output, "perfect", "her face changed", "too slow", or when you can see a defect yourself. Ratings feed the per-model stats in list_models and the model:"auto" choice, so an honest 2 helps more than a polite 4.
Parameters
| Name | Type | Constraints | Default | Description |
|---|---|---|---|---|
| run_id● | string | – | – | The job id the generate tool returned. |
| score● | integer | 1 to 5 | – | 1 = unusable, 3 = usable with edits, 5 = shipped as-is. |
| note | string | max 1000 chars | – | One line on why (optional). |
● required