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)

http
Authorization: Bearer przmad_sk_live_...

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

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

bash
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.