Skip to main content

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:

ParameterUse it for
image_asset_idArtwork already in your CoverScale library, from list_library_assets. Preferred.
image_upload_idA local file, uploaded with create_upload (or upload_file for a very small file).
image_urlA 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​

ToolWhat it doesParameters
get_accountThe account's tier, AI capabilities, credit balance and the scopes this connection holds.—
get_usageCredits spent and generations made over a window, by asset type.days (1–90, default 30), key_id
get_pricingThe credit price of avatars, banners and vinyl. Video prices are on list_motion_styles, not repeated here.—
list_motion_stylesEvery 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​

ToolWhat it doesParameters
list_library_assetsFinished assets, newest first, with names, types, sizes and a short-lived thumbnail.limit (1–50), cursor, asset_types, folder_id
get_library_assetOne asset.asset_id
list_library_foldersThe library's folders, to filter by.—

Uploads​

ToolWhat it doesParameters
upload_attached_fileStores 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_fileSends 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_uploadA 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.

ToolDeliversParameters beyond the source
generate_avatarsProfile artwork at every streaming platform's avatar size.typography
generate_bannersHeader artwork for every banner shape.typography
generate_vinylA vinyl mockup of the cover.appearance, back_image_url, vinyl_color, show_label, label_image_url, back_label_image_url
generate_spotify_canvasA 9:16 Canvas loop up to 8 seconds, silent.motion, prompt, typography, track (reference only, for bass_pulse and color_shift)
generate_youtube_visualizerA 16:9 visualizer, optionally muxed to a track.motion, prompt, track, audio_duration_s
generate_apple_motionApple Music motion artwork, 1x1 and 3x4, silent.motion, prompt, track (reference only)
generate_reelsA 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​

ToolWhat it doesParameters
get_jobA 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_jobsRecent jobs, newest first. The assistant checks here before resubmitting anything that timed out.limit, starting_after
wait_for_jobWaits 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_jobCancels a job. A queued job is refunded; one already generating stops and keeps its charge.job_id