Back to home

PAMA AI API Documentation

Create, inspect, and export AI moving-comic sequences through the PAMA AI v1 API.

Last updated: 2026-08-28

Overview

The PAMA AI v1 API creates asynchronous moving-comic sequences from a screenplay or short story idea. A sequence can analyze the script, derive a visual style, create storyboard images and motion clips, add music, and render a final MP4.

The machine-readable OpenAPI 3.1 document and API discovery document always describe the deployed API.

Authentication

Create an API key in Account settings → API Keys. Send it with either header:

Authorization: Bearer sk_your_api_key

or:

x-api-key: sk_your_api_key

Keep API keys server-side. Do not put them in browser JavaScript, public repositories, screenshots, or client applications.

Device-code login for agents and CLIs

An agent or CLI that does not already have a key can ask its user to approve a short-lived device code. Starting and polling this flow do not require authentication.

curl --request POST 'https://pama.ai/api/v1/device/code'

Display the returned user_code and open verification_url_complete in the user's browser. The user signs in to PAMA AI and explicitly approves or denies that code. Then poll the returned _links.poll.href, no faster than the advertised five-second interval:

curl 'https://pama.ai/api/v1/device/token?device_code=DEVICE_CODE&wait=60s'

The authorization expires after 10 minutes. While approval is pending the endpoint returns 428 authorization_pending; polling too fast returns 429 slow_down with Retry-After; denial returns 403 access_denied; and an unknown, expired, or already-consumed code returns 410 expired_token. On approval, api_key is returned exactly once. It is a normal revocable PAMA API key shown in Account settings → API Keys. The database stores hashes of both device codes, never their plaintext values.

Create a sequence

POST /api/v1/sequences accepts a script and starts production. Automatic style derives a private, sequence-specific visual bible from the script.

curl --request POST 'https://pama.ai/api/v1/sequences?wait=30s' \
  --header 'Authorization: Bearer sk_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "The Last Train",
    "script": "At sunrise, Lin waits alone on a misty mountain railway platform. A silver train arrives and warm light fills the station.",
    "enhance": "auto",
    "aspectRatio": "16:9",
    "styleId": "automatic",
    "analysisModel": "anthropic/claude-opus-5",
    "imageModel": "openai/gpt-image-2",
    "videoModel": "bytedance/seedance-2.0/enterprise/v2/image-to-video",
    "musicModel": "fal-ai/elevenlabs/music",
    "targetDurationSeconds": 30,
    "autoMotion": true,
    "autoMusic": true,
    "autoExport": true
  }'

The response is 202 Accepted. It contains the sequence state, production counts, links, and enhancedScript when enhancement ran. ?wait=30s waits only for the first state change or terminal result; it does not keep an HTTP request open for the entire render.

{
  "id": "seq_01JTRAIN",
  "title": "The Last Train",
  "status": "analyzing",
  "progress": 10,
  "aspectRatio": "16:9",
  "counts": {
    "storyScenes": 0,
    "shots": 0,
    "frames": 0,
    "renderSegments": 0,
    "scenes": 0,
    "imagesReady": 0,
    "motionReady": 0
  },
  "references": {
    "talentIds": [],
    "locationIds": [],
    "createdTalentIds": [],
    "createdLocationIds": []
  },
  "_links": {
    "self": { "href": "https://pama.ai/api/v1/sequences/seq_01JTRAIN" },
    "studio": { "href": "https://pama.ai/studio/sequences/seq_01JTRAIN" }
  }
}

Uploaded element rights

When elementReferenceUrls contains logos, products, screenshots, or other user-supplied media, include "elementReferenceAttestation": { "statementVersion": "asset-rights-v1" }. PAMA pins the exact server-owned statement, every referenced URL, and request context as append-only evidence before creating the sequence or consuming AI credits. Requests with missing or mismatched statements are rejected.

Script enhancement modes

  • auto — the default; expands a short script under 1,000 characters.
  • always — always expands the supplied script before analysis.
  • off — preserves the submitted script verbatim.

Enhancement is a separately credited AI operation. A failed enhancement is automatically refunded.

Styles

styleId accepts a built-in or personal Style UUID, exact name, or URL-style slug. Use automatic to derive and lock a structured visual direction from the script. List available built-in styles with GET /api/v1/styles.

Models and generated schemas

Use GET /api/v1/models before creating a sequence. It returns every selectable analysisModel, imageModel, videoModel, and musicModel, along with provider, credit cost, supported aspect ratios/durations/references, and a JSON Schema generated for that exact model ID. The same enums are embedded in OpenAPI, so an SDK or agent can validate a choice without copying limits from this page.

Talent and Location references

Use characters and locations to suggest reusable library assets before script analysis. A string may be an owner-visible asset ID, exact name, or URL-style slug. You can also create a text or media-backed library asset inline; it is automatically selected for this sequence.

{
  "characters": [
    "lin-the-conductor",
    {
      "name": "Mira",
      "description": "A calm apprentice conductor",
      "appearance": "Short black hair",
      "clothing": "Navy coat and red scarf",
      "continuityTag": "mira-v1",
      "referenceImageUrls": ["https://cdn.example.com/mira-reference.png"],
      "rightsAttestation": { "statementVersion": "asset-rights-v1" }
    }
  ],
  "locations": [
    "Misty Mountain Platform",
    {
      "name": "Silver Train Interior",
      "description": "A quiet overnight carriage",
      "visualPrompt": "Brushed steel, warm practical lights, blue dawn outside",
      "referenceImageUrls": ["https://cdn.example.com/train-interior.jpg"],
      "rightsAttestation": { "statementVersion": "asset-rights-v1" }
    }
  ]
}

PAMA resolves every string before creating inline assets or starting credited AI work. Unknown or cross-account references return UNKNOWN_REFERENCE; ambiguous names return AMBIGUOUS_REFERENCE and must be replaced with an exact ID. The 202 response includes references.talentIds, references.locationIds, and the IDs created inline. Existing talentReferenceIds and locationReferenceIds remain supported for exact-ID clients.

An inline object may contain up to five referenceImageUrls. PAMA applies SSRF protections: it rejects private, loopback, link-local, ambiguous numeric, IPv6, and internal-looking hosts; never follows redirects; requires an image response type; caps each response at 20 MB; and stores a PAMA-owned copy before writing the asset. A media-backed object requires a server-selected rights statement. Use asset-rights-v1 for synthetic Talent and Location media. If a Talent depicts a real identifiable person, set depictsRealPerson: true and use person-media-rights-v1 with a non-empty authorizationBasis. portraitAttestation is accepted as an OpenStory-compatible alias for rightsAttestation. Media rows and immutable evidence are committed atomically before credited AI work begins.

Inspect production

Use the returned _links.self.href, or call:

curl 'https://pama.ai/api/v1/sequences/SEQUENCE_ID?wait=60s' \
  --header 'Authorization: Bearer sk_your_api_key'

The response includes:

  • sequence status and percentage progress;
  • story-scene, shot, frame, and render-segment counts;
  • selected storyboard image and motion URLs;
  • music, poster, and error state;
  • Studio and export links.

wait accepts values such as 60s, 1500ms, or 1m and is capped at 90 seconds. Response headers X-Wait-Changed and X-Wait-Done report why the request returned.

List sequences with GET /api/v1/sequences?limit=20. Follow nextCursor exactly; cursors are opaque and must not be constructed or modified.

Enhance a script without creating a sequence

curl --request POST 'https://pama.ai/api/v1/scripts/enhance' \
  --header 'Authorization: Bearer sk_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "script": "A lighthouse keeper befriends a stranded whale.",
    "aspectRatio": "16:9",
    "targetDurationSeconds": 30,
    "targetSceneCount": 5,
    "styleId": "automatic"
  }'

Export the final MP4

List export history:

curl 'https://pama.ai/api/v1/sequences/SEQUENCE_ID/exports' \
  --header 'Authorization: Bearer sk_your_api_key'

Start or reuse a merged export with POST to the same URL. PAMA AI reuses an existing export when the selected clips and music have the same source hash.

Errors and retries

API errors use a stable envelope:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The sequence request is invalid.",
    "details": {}
  }
}

Use the HTTP status plus error.code; do not parse the human message. Retrying a request with the same accepted operation does not authorize duplicate billing. Failed credited AI tasks are refunded automatically, while a new retry is recorded as a separate attempt.

Authenticated endpoints allow 10 requests per API key in each one-second database-backed window. A limit response is 429 RATE_LIMITED and includes Retry-After; pause for that many seconds before retrying. The limit is shared across endpoints and Worker instances using the same key.

Limits

  • Script: 10–50,000 characters.
  • Sequence duration: 5–180 seconds.
  • Storyboard shots: 3–24.
  • Talent and Location references: up to 16 of each.
  • List page size: 1–100.
  • Long poll: up to 90 seconds.
  • Device authorization: expires after 10 minutes; poll every 5 seconds or use wait.
  • Authenticated API rate limit: 10 requests per API key per second.
  • Sequence creation currently enforces a minimum interval per authenticated API user.

Support

For API support, include the sequence ID, endpoint, UTC timestamp, HTTP status, and error.code. Never send an API key or provider secret. Contact support@pama.ai.