Skip to main content

CoverScale API

Generate release assets from one piece of artwork. Keys are minted in your CoverScale account under API access; this API is how an integration uses them.

Per-endpoint request and response schemas are in the API Reference. The same contract is served live at /v1/openapi.json.

Authenticating​

Every endpoint takes an API key as a bearer token:

Authorization: Bearer cs_live_<key_id>_<secret>

An API key is the credential your backend uses. There is no browser session, no ID token, and no App Check header — a request is authenticated entirely by the key in that one header, which is what makes it callable from your backend. The only other credential this API accepts is the OAuth access token (cs_oat_…) an AI assistant receives when someone connects it through the MCP server; you never handle one yourself.

GET /v1/me confirms a key works and reports the scopes, per-minute budget, tier and capabilities it carries:

curl -s https://api.coverscale.app/v1/me \
-H "Authorization: Bearer cs_live_..."

Against staging, use https://api-staging.coverscale.app.

API tier​

Access is granted per account, and by default an account has none — a key cannot be minted until it is. Two tiers:

  • basic — still asset types, and the local motions: ken_burns, split_layer, bass_pulse, light_leak and color_shift. Every request stays on our own hardware, so this is the tier for an integration you are building or testing: no call ever reaches a video-generation provider.
  • full — every pipeline the API supports.

A request outside the account's tier is refused with 403 tier_forbidden before anything is charged. GET /v1/generations/estimate lists every price this tier can submit. A motion it cannot run is left out.

Account capabilities​

Some accounts are set up to never send artwork to an AI model. For those, capabilities on GET /v1/me leaves out what they cannot use, and every generation still succeeds with a non-AI fallback:

  • without ai_analysis, still crops are centred instead of framed on the subject;
  • without gen_fill, a background is extended with a solid colour or a blurred backdrop;
  • without text_removal, typography: "remove" keeps the artwork as sent and says so in the job's typography report;
  • without gen_video, only the local motions can be submitted. Any other motion is refused with 403 capability_disabled before anything is charged, and is left out of GET /v1/generations/estimate;
  • without banners, POST /v1/generations/banners is refused with 403 capability_disabled before anything is charged.

Generating​

There is one endpoint per asset type, each accepting only the fields that apply to it:

EndpointDelivers
POST /v1/generations/avatarsProfile artwork at every DSP's avatar size
POST /v1/generations/bannersHeader artwork for every DSP banner shape
POST /v1/generations/vinylA physical-media mockup of the cover
POST /v1/generations/spotify-canvasA 9:16 looping Spotify Canvas clip, up to 8 seconds
POST /v1/generations/youtube-visualizerA 16:9 visualizer, about 8 to 12 seconds, optionally muxed to a track
POST /v1/generations/apple-motionApple Music motion artwork, 10 to 18 seconds, both shapes
POST /v1/generations/reelsA 15-second 9:16 clip for Reels and Shorts, optionally muxed to a track

Each returns immediately with a job. Poll GET /v1/jobs/{job_id} until status is succeeded, failed, or cancelled, or supply a webhook_url and be told.

GET /v1/generations/estimate returns every price this tier can submit, in one response, and takes no body. It accepts generations:read or generations:write. Video types have one price per motion this tier can run. Vinyl has the front-only price and the price with a back cover. Avatars and banners have a single price. The artwork itself never changes the charge, and neither do prompt, audio_url, typography, vinyl color, or label art. high, calm, and custom_prompt are the same price.

curl -s https://api.coverscale.app/v1/generations/avatars \
-H "Authorization: Bearer cs_live_..." \
-H "Content-Type: application/json" \
-d '{"image_url":"https://example.com/cover.jpg"}'

POST /v1/jobs/{job_id}/cancel asks a job to stop. A job that has not started yet is cancelled and refunded immediately. A job that is already generating stops at its next stage boundary and is not refunded.

GET /v1/jobs lists this account's jobs, newest first, for reconciling against your own records or finding a job_id you never managed to store. It returns a summary per job — status, asset type, credits charged — and no files; fetch GET /v1/jobs/{job_id} for the signed outputs. Page with limit and starting_after:

curl -s "https://api.coverscale.app/v1/jobs?limit=20" \
-H "Authorization: Bearer cs_live_..."

Sources​

Every generation takes its artwork from exactly one of:

  • image_url — an HTTPS URL that resolves to a public address. We fetch it.
  • image_upload_id — a file you uploaded through POST /v1/uploads.
  • image_asset_id — an asset from this account's library (GET /v1/library/assets). Its original artwork is used.

Where an endpoint takes a track, audio_upload_id works in place of audio_url.

To use a file that is not on a public URL, ask for an upload, PUT the file, and send its id:

curl -s https://api.coverscale.app/v1/uploads \
-H "Authorization: Bearer cs_live_..." \
-H "Content-Type: application/json" \
-d '{"content_type":"image/png"}'
# → {"upload_id": "…png", "upload_url": "https://storage.googleapis.com/…", "headers": {…}, …}

curl -s -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
-H "x-goog-content-length-range: 0,26214400" \
--data-binary @cover.png

Send every header in headers, or storage refuses the PUT. The URL is good for 30 minutes and the upload for 24 hours. Images are PNG, JPEG or WebP up to 25 MB; audio is MP3, WAV or M4A up to 50 MB — the same limits as a URL source. An account can request 30 uploads an hour. Uploading needs the uploads:write scope and reading the library needs library:read; keys minted before these scopes existed hold neither, so mint a new key to use them.

If the caller cannot reach the storage host, POST /v1/uploads/content with the file as the body and its MIME type as Content-Type stores it directly and returns the same kind of upload_id. Same types, size limits and hourly cap.

An upload or library id from another account is refused with 400 invalid_source before anything is charged, and checked again before the file is read.

Delivered files​

A finished job carries outputs, one entry per platform spec. Each url is on this API and lasts an hour. An image is the file itself, so a chat can show it; a video redirects to the file. Poll again for a fresh one rather than storing it. A tracking parameter added to the link does not break it. An OAuth caller, including the MCP server, saves the same generation to the account's asset hub unless the request sets save_to_library to false. An API key saves it only when the request sets save_to_library to true.

Video outputs are silent by default. Each endpoint chooses the length: Spotify Canvas stays within 8 seconds, the YouTube visualizer is about 8 to 12 seconds, and Reels / Shorts are 15 seconds. Apple Motion is 15 seconds, except high, calm and custom_prompt: those deliver the model's clip twice over, so 18 seconds (PixVerse), 16 (Veo) or 10 (Seedance, Kling). /v1/generations/youtube-visualizer and /v1/generations/reels are the exceptions on audio: supply audio_url, with any motion, and the delivered video is looped and muxed to that track's own length instead. audio_start_s and audio_duration_s pick the part of the track to use.

Spotify Canvas and Apple Motion stay silent, so there audio_url is only a reference: bass_pulse reads it, from audio_start_s, and requires it. Every other motion refuses a track on those two endpoints, since it would change nothing. A track that cannot be read, runs past 8 minutes, or is started past its end is refused with 400 invalid_audio before anything is charged.

/v1/generations/apple-motion delivers both a 1x1 and a 3x4 file from one generation and one charge.

Vinyl mockups​

/v1/generations/vinyl composites your cover art, text included, into a physical-media mockup rather than resizing it. Cover text stays on every generation except Spotify Canvas on the full tier, which strips it when the account has text removal. On the basic tier Canvas keeps the text unless the request sets typography to remove. typography: "preserve" keeps it on either tier. Avatars and banners also keep it unless typography is auto or remove. sleeve12 has no back cover. A back cover is a second render from its own source (so it bills a second credit). Custom label art is only accepted for a side that actually shows a label. A contradictory combination is a 400 invalid_option naming which field to change, before anything is charged.

Webhooks​

When a job reaches a terminal state we POST the job to your webhook_url with two headers:

  • CoverScale-Event — generation.succeeded, generation.failed, or generation.cancelled
  • CoverScale-Signature — t=<unix>,v1=<hex>

Verify it by recomputing HMAC-SHA256 over "{t}.{raw_body}" with the webhook_secret you were given when the key was created, and comparing against v1 in constant time. Reject anything whose t is older than your chosen tolerance.

Webhook delivery is a convenience with bounded retries. Polling is the guaranteed path — if an endpoint of yours is unreachable, the asset was still produced and GET /v1/jobs/{job_id} will show it.

Retrying a submit​

A submit charges. If a submit times out or the connection drops, you do not know whether it landed, and sending it again is a second charge for the same asset. There are two ways not to pay twice.

The plain one needs nothing from you: call GET /v1/jobs and look at the most recent job before resubmitting. Anything the first attempt created is there, whether or not you ever saw the response.

The other is an optional Idempotency-Key header — any string you can reproduce, usually a UUID your side already has:

Idempotency-Key: 3f1c0b2e-7a4d-4c1e-9b2a-6d5e8f0a1c23

A retry carrying the same key returns the original job instead of charging again, so the retry needs no lookup and no branch. Reusing a key with a different body, or against a different endpoint, is a 409 rather than a silent hand-back of an asset you did not ask for.

Everything else in this API is already safe to repeat: GET is a read, and cancelling an already-cancelled job returns it unchanged.

Errors​

Every failure carries {"error": "<code>", "message": "<prose>"}. Branch on error; message is for humans and may change.

StatuserrorMeaning
401unauthorizedThe API key is missing, unknown, or revoked
400invalid_sourceAn upload or library id is unknown, expired, or not yours
429rate_limitedThe key's per-minute budget is spent
402insufficient_creditsThe account is out of credits
403api_access_disabled / tier_forbiddenThe account or its tier does not cover this request
403capability_disabledThe account may not use the AI feature this request needs
422invalid_requestThe body does not match the endpoint's schema
400invalid_optionEvery field is valid but the combination is not (vinyl rules)
400invalid_audioThe track cannot be read, runs past 8 minutes, or starts past its end

422 is a field that does not belong on that endpoint (vinyl_color on /avatars). 400 is a valid field whose combination is impossible. Both are raised before anything is charged.

Changes​

2026-11-11 — Library saving, Canvas text on basic, and track checks. An API key copies a finished generation into the asset hub only when the request sets save_to_library: true. An OAuth caller, including the MCP server, still saves unless it sets save_to_library: false. On the basic tier, Spotify Canvas treats an omitted typography (auto) as preserve, so cover text stays; typography: "remove" still strips it when the account has text removal. A track that cannot be read, runs past 8 minutes, or is started past its end is refused with 400 invalid_audio before anything is charged. GET /v1/generations/estimate accepts generations:read as well as generations:write.

2026-11-09 — Uploads and library sources. POST /v1/uploads returns a signed URL to PUT a local image or track to, and GET /v1/library/assets lists the account's saved assets. Every generation now takes exactly one of image_url, image_upload_id or image_asset_id, so image_url is no longer required on its own (a generated SDK sees it change from string to string | null; existing calls behave the same); tracks take audio_upload_id in place of audio_url. Two new scopes guard these, uploads:write and library:read, and new keys get them by default. The API also accepts OAuth access tokens issued to AI assistants through the new MCP server.

2026-10-30 — Apple Motion follows Apple's 8-second floor. Apple Music now accepts motion artwork from 8 to 35 seconds. On /v1/generations/apple-motion, high, calm and custom_prompt now deliver the model's clip twice over: 18 seconds from PixVerse (was 15), 16 from Veo and 10 from Seedance or Kling. They cost 6 credits instead of 7. Every other Apple Motion motion is unchanged at 15 seconds and its old price.