api-usage

name	api-usage
description	REST API for creating AI-powered video ads programmatically. Bearer token auth via API key, OAuth client_credentials, or OAuth Authorization Code (Connect flow).
version	1.1.0

Prizmad REST API

Prizmad provides a REST API for creating AI-powered video ads programmatically. The MCP server at /api/mcp is a thin agent-friendly wrapper on top of these endpoints — anything the MCP layer does, you can do with a curl loop.

Authentication

Three interchangeable ways to obtain a Bearer token. See /.well-known/agent-skills/oauth/SKILL.md for the full OAuth spec.

Option 1: API key (simplest)

Authorization: Bearer przmad_sk_live_...

Manage keys at https://prizmad.com/api-keys.

Option 2: OAuth 2.0 client_credentials (server-to-server)

curl -X POST https://prizmad.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=my-app \
  -d client_secret=przmad_sk_live_...

Returns access_token (HS256 JWT, 1 h, audience https://prizmad.com/api).

Option 3: OAuth 2.1 Authorization Code + PKCE + DCR (Connect flow)

The "Add custom connector" path used by Claude Desktop / Claude.ai / ChatGPT / Cursor. RS256 JWT bound to the MCP audience, refresh-rotated. Discovery: /.well-known/oauth-authorization-server.

Discovery

• OpenAPI: https://prizmad.com/openapi.json
• Interactive docs (Scalar): https://prizmad.com/api/docs
• API catalog (RFC 9727): https://prizmad.com/.well-known/api-catalog
• Health: https://prizmad.com/api/health

Endpoints

Public (no auth)

Method	Path	Purpose
GET	/api/v1/templates	List all video templates with features and token costs
GET	/api/v1/avatars	List built-in avatar presets with recommended voices

Authenticated

Method	Path	Purpose
GET	/api/v1/videos	List the caller's recent video projects (paginated; ?limit, ?status). Returns projectUrl / shareUrl / downloadUrl per row.
POST	/api/v1/videos	Create a new video render. Returns videoId + estimated time + poll cadence. Requires Pro plan.
GET	/api/v1/videos/{id}	Status by id — progress %, steps, projectUrl, shareUrl, downloadUrl, errorMessage. Auto-mints a share token on completion.
GET	/api/v1/videos/{id}/download	Authenticated mp4 stream proxied through prizmad.com.
POST	/api/v1/videos/batch	Launch up to 20 renders in parallel; pre-checks total token cost.
POST	/api/v1/upload	Multipart upload for one or more product / avatar images.
POST	/api/v1/upload-from-url	JSON upload (image URL or base64 blob) — agent-friendly. Returns a prizmad.com-hosted URL.

Output URLs

Every video status response carries three URL kinds, in priority order:

Field	Goes to
projectUrl	Owner-only dashboard /projects/<id> (full remix / edit / asset / download) — primary link to give the signed-in user.
shareUrl	Public /share/<token> page — only for forwarding outside the account.
downloadUrl	Authenticated /api/v1/videos/<id>/download mp4 proxy.

The raw Vercel Blob URL is never part of the public response; downloads always flow through prizmad.com.

Plan + token rules

• API generation requires a Pro plan (POST /api/v1/videos returns 403 with an upgrade URL otherwise).
• Tokens come from the user's monthly plan first, then any top-up balance.
• Insufficient balance returns 402 with required, balance, and topUpUrl.

Rate limits

• 10 requests per minute per API key on most endpoints.
• 30 requests per minute on the MCP endpoint.
• Token consumption per create_video is template-specific — see the cost field in /api/v1/templates.