Endpoints

Confirm the reviewed current inputs of an older paused job.

Requires jobs:read and the matching images:generate or videos:generate scope. Read requiredAction, show its ordered previews and pricing, obtain user approval, then echo inputFingerprint. A stale review returns 409. Reuses the existing job and reservation; retrying the same accepted fingerprint does not create or fund another job.

Request body

Start an image generation and return the job to poll.

Only prompt is required — the server chooses a resolution and aspect ratio when they are omitted. Responds 202 with a job; poll GET /v1/jobs/:id (or follow Location) until it reaches succeeded or failed. Requires an Idempotency-Key, so a retried request returns the original job instead of rendering and charging twice. For media created for a Layers design, pass its designId; edit access is required and the admin-configured Layers multiplier applies (default 3.5×) instead of the API multiplier.

Request body

Start a video generation and return the job to poll.

As POST /v1/images, plus duration, audio, and video/audio references. Accepted durations, resolutions and reference limits depend on the configured model — read GET /v1/capabilities rather than hardcoding them. A video whose cast needs character sheets pauses at action_required; approve it to continue.

Request body

Fetch one job created through the API.

Result URLs are signed for this response only and carry result.expiresAt — sign them again by re-reading the job rather than storing them. Jobs created in the Musavir studio are not readable with an API key and answer 404. A running job may still be rendering or may be securing its finished output; keep the job id and continue polling until a terminal status instead of imposing a short client-side timeout.

List jobs created through the API, newest first.

Every key on the account sees the same account-wide list, filtered to API-origin jobs. Pass pagination.nextCursor back as cursor for the next page; a cursor is opaque and must not be parsed or constructed.

Query parameters

Approve the character sheets a video job is waiting on.

Only meaningful while the job reports action_required; the sheets to review are in requiredAction.previews. Approving an already approved job returns that job, so a retry after a lost response is safe.

Presign reference-image uploads for an image or video generation.

PUT the file bytes directly to uploadUrl with exactly the headers in headers. The bytes never pass through this API. sizeBytes is REQUIRED and is signed into the URL: the upload must be exactly that many bytes or storage rejects it, so a URL cannot be reused for a larger file than it was issued for. maxBytes is rechecked from the stored object when the reference is used as well. The returned uploadKey is opaque. Store it and pass it back verbatim — never parse it, derive one from a filename, or construct one by hand; its layout is server-owned and can change without a version bump, and a key outside your own namespace is rejected. How many of these keys one generation may carry depends on its cast — each character reserves provider slots — so read /v1/capabilities for the budget rather than assuming this endpoint’s ceiling.

Request body

Presign MP4/MOV reference-clip uploads for a video generation.

PUT the file bytes directly to uploadUrl with exactly the headers in headers. The bytes never pass through this API. sizeBytes is REQUIRED and is signed into the URL: the upload must be exactly that many bytes or storage rejects it, so a URL cannot be reused for a larger file than it was issued for. maxBytes is rechecked from the stored object when the reference is used as well. The returned uploadKey is opaque. Store it and pass it back verbatim — never parse it, derive one from a filename, or construct one by hand; its layout is server-owned and can change without a version bump, and a key outside your own namespace is rejected. A reference clip must then be normalized through POST /v1/uploads/videos/normalize, which is the only place its duration and dimensions are actually checked. How many clips one generation accepts is model-dependent — see videos.references.maxVideoReferences in /v1/capabilities.

Request body

Presign MP3/WAV reference-audio uploads for a video generation.

PUT the file bytes directly to uploadUrl with exactly the headers in headers. The bytes never pass through this API. sizeBytes is REQUIRED and is signed into the URL: the upload must be exactly that many bytes or storage rejects it, so a URL cannot be reused for a larger file than it was issued for. maxBytes is rechecked from the stored object when the reference is used as well. The returned uploadKey is opaque. Store it and pass it back verbatim — never parse it, derive one from a filename, or construct one by hand; its layout is server-owned and can change without a version bump, and a key outside your own namespace is rejected. How many audio references one generation accepts is model-dependent — see videos.references.maxAudioReferences in /v1/capabilities.

Request body

Normalize a reference clip, retaining the original metadata response contract.

After the PUT, queue durable preparation and wait at most 25 seconds. Success returns the original video_reference fields: authoritative uploadKey, durationSeconds, width, height, normalized. Always use that returned uploadKey. If preparation is still pending, HTTP 503 provider_unavailable and Retry-After include the original uploadKey and, once retained, preparationId. Retry with the SAME original uploadKey and allowTrim to recover the existing preparation; no decoder work runs inside this request and no credits are spent. For immediate 202 receipts use POST /v1/uploads/videos/prepare instead. An overlong clip returns VIDEO_TRIM_CONSENT_REQUIRED with measured durationSeconds/maxDurationSeconds. Obtain permission, then retry the original uploadKey with allowTrim: true. Raw uploads remain until the saved prepared result has passed its cleanup grace.

Request body

Queue reference-video preparation and immediately return a durable receipt.

Returns 202 and Location while queued or running, or 200 for a terminal replay. Poll GET /v1/uploads/preparations/:id until succeeded, then use result.key as the authoritative uploadKey. Retrying the same original uploadKey and allowTrim reuses the existing receipt. A failed receipt carries safe errorCode, errorMessage and optional measured trim errorDetails. No decoder work runs in this HTTP request and no credits are spent.

Request body

Read an owned upload preparation receipt.

Poll until status is succeeded or failed. Succeeded result.key is the authoritative prepared upload key; failure contains a safe errorCode, errorMessage and optional trim consent errorDetails. This read does not decode media or buy a generation.

Create a character as a draft, before it has any photos.

Costs nothing and starts nothing. Keep the returned id: the draft is where selfies are uploaded and it is NOT returned by GET /v1/characters, which lists characters that have begun training — an abandoned draft must not sit in a library looking like a broken character. GET /v1/characters/{id} returns it throughout.

Request body

Presign selfie uploads into this character’s own namespace.

PUT each file directly to its uploadUrl with exactly the headers in headers, then pass the returned uploadKey values to the train action. These keys are NOT interchangeable with generation reference keys — each namespace is refused by the other — and the accepted content types differ: selfies take the HEIC/HEIF a phone camera produces and refuse GIF. Read characters.selfieContentTypes from /v1/capabilities rather than hardcoding either list.

Request body

Attach the uploaded selfies and start training. Returns 202.

Requires an Idempotency-Key: this is the call that spends credits, and a retry must return the same character rather than train it twice. Only keys returned by this character’s own upload endpoint are accepted. Poll GET /v1/characters/{id} until status is ready or failed. Stop automatic training retries for awaiting_confirmation (review the ordered photos in Studio) or reconciliation_pending (the saved avatar is available; billing needs reconciliation). A 402 here means the balance could not cover training.

Request body

The account’s characters, newest first, cursor-paginated.

Characters created in the studio are listed alongside those created through the API: a character is an account resource, and using one an integration did not create is the point of the scope. Drafts that have not started training are excluded. Follow pagination.nextCursor rather than assuming one page holds everything.

Query parameters

One character: status, progress, and a freshly signed avatar URL.

The avatar URL is signed for this response only and dies at avatar.expiresAt — never store it, re-read the character instead. A character belonging to another account is a 404, the same answer as one that does not exist.

Credit balance, plan, auto-reload settings, and API usage for the current billing period.

Credit amounts are decimal strings with six decimal places. Usage is reported both account-wide and for the calling key, over the period named in period. The autoReload block explains why a balance may refill on its own: whether automatic top-ups are on, the balance that triggers one, how much each adds, the monthly ceiling, how much has been added so far this UTC calendar month, and why the last attempt stopped. It is READ-ONLY here, and there is no endpoint in /v1 that changes it — an API key may never alter a payment setting. Auto-reload is a standing permission to charge a saved card with nobody present, so switching it on or changing what it charges is a signed-in action in the Musavir studio, taken by the person who owns the card rather than by a key that could be copied out of a config file.

The calling key's rate-limit budgets, when limiting is enabled.

Reading this endpoint does not consume any budget. The generation budget is listed even though this call is not a generation, so a client can plan a batch before it starts.

Durations, resolutions, ratios, media types and reference limits the models accept.

The runtime source of truth. Values here are read from the live server configuration on every request, so they follow a model change without a documentation or SDK release. Never hardcode a duration or resolution against the documented examples instead of this.