MCP tools
Each tool calls the REST API as you, with the connection's own permissions, so anything the API refuses the tool reports back to the assistant in words it can act on.
Shared parameters
The seven generate_* tools take their artwork from exactly one of:
| Parameter | Use it for |
|---|---|
image_asset_id | Artwork already in your CoverScale library, from list_library_assets. Preferred. |
image_upload_id | A local file, uploaded with create_upload (or upload_file for a very small file). |
image_url | A public https:// link. |
Tools that take a track accept audio_upload_id or audio_url (not both), with audio_start_s and, where the clip is muxed to the track, audio_duration_s.
Every generate_* tool also takes an optional folder_id (from list_library_folders) and name. Omit them and a generation from a library asset is saved in that asset's folder, under that asset's name. A file or URL source is saved without a name, in Unsorted.
Every generate_* tool also takes an optional idempotency_key. Without one, the server derives a key from the request itself, so a network retry of the same request within five minutes returns the same job instead of charging twice; a retry later than that is a new submit, and a new request is always a new generation. An assistant that needs retries to be exact passes its own idempotency_key.
save_to_library copies the finished generation into the account's asset hub. Omitted, this connection saves, because it signs in with OAuth. Set it to false to skip the hub. An API key does the opposite: it saves only when the field is true.
Account
| Tool | What it does | Parameters |
|---|---|---|
get_account | The account's tier, AI capabilities, credit balance and the scopes this connection holds. | — |
get_usage | Credits spent and generations made over a window, by asset type. | days (1–90, default 30), key_id |
get_pricing | The credit price of avatars, banners and vinyl. Video prices are on list_motion_styles, not repeated here. | — |
list_motion_styles | Every motion style with what it looks like and its price per video type. An empty price means the tier cannot use it. | asset_type |
Library
| Tool | What it does | Parameters |
|---|---|---|
list_library_assets | Finished assets, newest first, with names, types, sizes and a short-lived thumbnail. | limit (1–50), cursor, asset_types, folder_id |
get_library_asset | One asset. | asset_id |
list_library_folders | The library's folders, to filter by. | — |
Uploads
| Tool | What it does | Parameters |
|---|---|---|
upload_attached_file | Stores a file the host attached by link, unchanged, and returns its upload_id. The host fills in the link. A client that does not is told to use create_upload. The link is only followed on the host's file servers. Images up to 25 MB, audio too. | file (filled in by the host) |
upload_file | Sends a small file itself (base64, up to 8 MB decoded) and returns its upload_id. A cover image is too much text to pass through a chat. Use create_upload for that. | content_base64, content_type |
create_upload | A URL on the CoverScale API for one local file, plus the curl command that uploads it. Images (PNG, JPEG, WebP) up to 25 MB, audio (MP3, WAV, M4A) up to 50 MB. Any client that can run a command uses this. The curl posts to the CoverScale API and does not touch storage.googleapis.com. A host that already passed a download link uses upload_attached_file instead. | content_type |
Generations
All of these spend credits and return a job straight away. The assistant confirms the price with you first, in text, and does not draw a preview of the result. It uploads your file unchanged. Finished images show in the chat; videos arrive as links.
| Tool | Delivers | Parameters beyond the source |
|---|---|---|
generate_avatars | Profile artwork at every streaming platform's avatar size. | typography |
generate_banners | Header artwork for every banner shape. | typography |
generate_vinyl | A vinyl mockup of the cover. | appearance, back_image_url, vinyl_color, show_label, label_image_url, back_label_image_url |
generate_spotify_canvas | A 9:16 Canvas loop up to 8 seconds, silent. | motion, prompt, typography, track (reference only, for bass_pulse and color_shift) |
generate_youtube_visualizer | A 16:9 visualizer, optionally muxed to a track. | motion, prompt, track, audio_duration_s |
generate_apple_motion | Apple Music motion artwork, 1x1 and 3x4, silent. | motion, prompt, track (reference only) |
generate_reels | A 15-second 9:16 clip for Reels and Shorts, optionally muxed to a track. | motion, prompt, track, audio_duration_s |
motion is one of the styles list_motion_styles returns. typography is auto, remove or preserve. Avatars and banners keep the cover text (preserve). Spotify Canvas on the full tier removes it (auto) when the account has text removal, and preserve keeps it. On the basic tier Canvas keeps the text unless typography is remove. A vinyl mockup always keeps the text. The record is black unless you name a color.
Jobs
| Tool | What it does | Parameters |
|---|---|---|
get_job | A job's status and, once it succeeded, its files. Each file comes back as the image itself when it is an image, as one frame when it is a video, and as a named link either way. Links expire after 24 hours. | job_id |
list_jobs | Recent jobs, newest first. The assistant checks here before resubmitting anything that timed out. | limit, starting_after |
wait_for_job | Waits up to 90 seconds for a job to finish and returns it, including a finished image or a video frame. A job that is still running says so; ask again with the same job. It does not charge again. | job_id, timeout_s |
cancel_job | Cancels a job. A queued job is refunded; one already generating stops and keeps its charge. | job_id |