PAMA AI API 文档

通过 PAMA AI v1 API 创建、查询并导出 AI 漫剧作品。

最近更新: 2026-08-28

概览

PAMA AI v1 API 可以把剧本或故事创意异步制作成 AI 漫剧。一次作品制作可包含剧本分析、视觉风格生成、分镜图、动态视频、配乐和最终 MP4 导出。

身份验证

请在 账户设置 → API Keys 创建 API Key，并通过以下任一请求头发送：

Authorization: Bearer sk_your_api_key

或：

x-api-key: sk_your_api_key

API Key 只能保存在服务端。请勿放入浏览器 JavaScript、公开代码仓库、截图或客户端应用。

Agent 与 CLI 的设备码登录

尚未持有 API Key 的 Agent 或 CLI，可以让当前用户在浏览器中确认一个短时有效的设备码。创建和轮询设备码都不需要预先认证。

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

向用户展示返回的 user_code，并在浏览器中打开 verification_url_complete。用户登录 PAMA AI 后明确批准或拒绝该设备码。随后按返回的五秒 interval 轮询 _links.poll.href，不要更频繁；也可以使用长轮询：

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

授权会在 10 分钟后过期。等待批准时返回 428 authorization_pending；轮询过快返回带 Retry-After 的 429 slow_down；拒绝返回 403 access_denied；设备码不存在、已过期或已经兑换时返回 410 expired_token。批准后只返回一次 api_key。它是普通、可撤销的 PAMA API Key，可在 账户设置 → API Keys 中管理。数据库仅保存设备码的哈希，不保存明文。

创建作品

POST /api/v1/sequences 接收剧本并启动制作。使用 Automatic 风格时，PAMA AI 会根据剧本生成并固化该作品专属的视觉风格规范。

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": "末班车",
    "script": "日出时，林独自在云雾缭绕的山间站台等待。一列银色列车进站，温暖的灯光照亮车站。",
    "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
  }'

接口返回 202 Accepted，内容包含作品状态、制作数量和后续链接；若执行了剧本增强，还会返回 enhancedScript。?wait=30s 只等待第一次状态变化或终态，不会让 HTTP 请求一直等待完整渲染结束。

{
  "id": "seq_01JTRAIN",
  "title": "末班车",
  "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" }
  }
}

上传元素素材的权利声明

当 elementReferenceUrls 包含 Logo、产品图、截图或其他用户上传素材时，必须同时传入 "elementReferenceAttestation": { "statementVersion": "asset-rights-v1" }。PAMA 会在创建作品或扣除 AI 积分前，将服务端固定声明、全部参考 URL 与请求上下文记录为不可覆写的证据；声明缺失或版本不匹配的请求会被拒绝。

剧本增强模式

auto — 默认模式；剧本少于 1,000 字符时自动扩写。
always — 无论长短都先扩写再分析。
off — 完整保留提交的原始剧本。

剧本增强会单独扣除积分；任务失败时自动退还。

风格

styleId 支持内置或个人风格的 UUID、完整名称或 URL slug。传入 automatic 时会根据剧本生成结构化视觉方向并锁定在当前作品。可通过 GET /api/v1/styles 获取内置风格列表。

模型与自动生成 Schema

创建作品前可调用 GET /api/v1/models。接口返回全部可选的 analysisModel、imageModel、videoModel、musicModel，同时提供供应商、积分成本、比例、时长、参考素材能力，以及为该精确模型 ID 自动生成的 JSON Schema。OpenAPI 中也包含同一组枚举，SDK 或 Agent 无需复制本文限制即可校验模型选择。

人物与场景引用

使用 characters 和 locations，可以在剧本分析前指定可复用素材库资产。字符串可以是当前账户可见的资产 ID、完整名称或 URL slug；也可以直接传入纯文本或带参考图的对象创建新资产，新资产会自动用于本次作品。

{
  "characters": [
    "lin-the-conductor",
    {
      "name": "米拉",
      "description": "沉稳的见习列车员",
      "appearance": "黑色短发",
      "clothing": "藏蓝外套与红色围巾",
      "continuityTag": "mira-v1",
      "referenceImageUrls": ["https://cdn.example.com/mira-reference.png"],
      "rightsAttestation": { "statementVersion": "asset-rights-v1" }
    }
  ],
  "locations": [
    "雾山站台",
    {
      "name": "银色列车车厢",
      "description": "安静的夜行列车车厢",
      "visualPrompt": "拉丝钢材、暖色实景灯、窗外蓝色黎明",
      "referenceImageUrls": ["https://cdn.example.com/train-interior.jpg"],
      "rightsAttestation": { "statementVersion": "asset-rights-v1" }
    }
  ]
}

PAMA 会先解析全部字符串引用，再创建内联资产或启动任何扣积分的 AI 工作。不存在或跨账户的引用返回 UNKNOWN_REFERENCE；重名引用返回 AMBIGUOUS_REFERENCE，此时必须改用精确 ID。202 响应会披露 references.talentIds、references.locationIds 以及本次内联创建的 ID。原有 talentReferenceIds 和 locationReferenceIds 仍可供只使用精确 ID 的客户端兼容调用。

每个内联对象最多可携带五个 referenceImageUrls。PAMA 会拒绝私网、回环、链路本地、含糊数字、IPv6 与内部域名，不跟随跳转，只接受真实图片响应类型，并将单张图片限制在 20 MB；校验通过后会先转存为 PAMA 自有对象，再写入资产。带参考图的对象必须使用服务端指定的权利声明：合成人物与场景使用 asset-rights-v1；若 Talent 对应真实可识别人物，需设置 depictsRealPerson: true，并传入带非空 authorizationBasis 的 person-media-rights-v1。portraitAttestation 可作为兼容 OpenStory 的 rightsAttestation 别名。素材记录和不可覆写证据会在任何 AI 扣费前原子提交。

查询制作进度

使用响应中的 _links.self.href，或调用：

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

响应包括：

作品状态与进度百分比；
故事场景、镜头、关键帧和渲染片段数量；
当前选中的分镜图与动态视频 URL；
配乐、海报与错误状态；
Studio 和导出链接。

wait 支持 60s、1500ms、1m 等格式，最长 90 秒。响应头 X-Wait-Changed 与 X-Wait-Done 会说明返回原因。

使用 GET /api/v1/sequences?limit=20 分页查询作品。请直接使用响应中的 nextCursor；游标是不透明值，不能自行构造或修改。

仅增强剧本

curl --request POST 'https://pama.ai/api/v1/scripts/enhance' \
  --header 'Authorization: Bearer sk_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "script": "一位灯塔管理员救下了一头搁浅的鲸鱼。",
    "aspectRatio": "16:9",
    "targetDurationSeconds": 30,
    "targetSceneCount": 5,
    "styleId": "automatic"
  }'

导出最终 MP4

查询导出历史：

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

向同一 URL 发送 POST 可开始或复用合并导出。若当前选中的视频片段与配乐具有相同 source hash，PAMA AI 会直接复用已有导出。

错误与重试

API 错误使用固定结构：

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

请依据 HTTP 状态码与 error.code 处理错误，不要解析自然语言消息。对已接受操作的重复请求不会授权重复计费。失败的积分任务会自动退款；新的重试会作为独立尝试记录。

已认证接口按每个 API Key 每秒最多 10 个请求限制，计数由数据库保存并在不同 Worker 实例间共享。超过限制时返回 429 RATE_LIMITED 和 Retry-After；请等待该秒数后再重试。一个 Key 对不同接口的请求会合并计数。

限制

剧本长度：10–50,000 字符。
作品时长：5–180 秒。
分镜镜头：3–24 个。
人物与场景引用：各最多 16 个。
列表每页：1–100 条。
长轮询：最长 90 秒。
设备授权：10 分钟后过期；每 5 秒轮询一次，或使用 wait。
已认证 API 限制：每个 API Key 每秒 10 个请求。
创建作品目前按已认证 API 用户执行最小请求间隔限制。

技术支持

提交 API 问题时，请提供作品 ID、接口路径、UTC 时间、HTTP 状态码和 error.code。请勿发送 API Key 或模型服务密钥。联系 support@pama.ai。