Overview & quickstart

Promoat Partner API

Generate AI presenter videos from your own backend: create a character, pick or clone a voice, and queue talking-head or scene videos — then edit them scene by scene. Plain JSON over HTTPS, pay-per-use credits, no SDK required.

What you can build

The Partner API is the same pipeline that powers Promoat, exposed as REST endpoints for your product. The building blocks compose in one flow:

Characters — an AI presenter identity, cloned from selfies or invented from a description.
Voices — clone a real voice from audio samples (your first clone is free), or pick a free studio voice.
TTS & first-frame images — speech audio and still frames as standalone outputs.
Videos — the headline act: a vertical talking-head video, or a scene video where the character acts the script out across clips (with a voice or silent).
Video edits — redo one scene, rewrite a line, or replace the sound without starting over.

Everything you generate lands in your asset ledger with a durable URL, and every job is billed in credits against your prepaid balance.

New in 1.1

New video engines (sharper output, default resolution 768P, lower prices — a 15 s talking head is 125 credits), scene plans and video edits, idempotency keys, expected_credits, and an error_code on every error (since 1.1.1). Start with What's new in 1.1; the changelog has every detail.

Base URL & auth in one look

The API lives on the same origin as these docs. Every endpoint sits under /api/partner/v1/ and takes your key as a bearer token:

The shape of every request

curl https://platform.promoat.ai/api/partner/v1/usage/summary \
  -H "Authorization: Bearer $PROMOAT_KEY"

Where your key comes from

Your pmat_… key is issued in the partner dashboard. Details and safety notes in Authentication.

Quickstart: zero to your first video

Five requests. Steps 2–3 are one-time setup you reuse for every video after that.

Check your balance

GET /usage/summary

curl https://platform.promoat.ai/api/partner/v1/usage/summary \
  -H "Authorization: Bearer $PROMOAT_KEY"

# → { "credits_balance": 1131, ... }

Create a character (your presenter)

POST /characters — free

curl -X POST https://platform.promoat.ai/api/partner/v1/characters \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ava",
    "description": "a friendly, upbeat presenter in her early 30s"
  }'

# → { "character_id": "…", "sheet_image_url": "…", "credits_charged": 0 }

Get a voice (free studio voice, or clone a real one)

POST /voices — studio voices are free; clones are 30 credits (your first is free)

curl -X POST https://platform.promoat.ai/api/partner/v1/voices \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ava voice", "studio_voice": "Sarah", "language": "english" }'

# → { "voice_id": "…", "kind": "library", "credits_charged": 0 }
# (to clone a real voice instead, send sample_urls — see the Voices guide)

Check the price, then queue the video

POST /videos/estimate → POST /videos

# Same body for both — the quote equals the reserve.
curl -X POST https://platform.promoat.ai/api/partner/v1/videos/estimate \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "talking_head",
    "character_id": "CHARACTER_ID",
    "voice_id": "VOICE_ID",
    "script": "Hi! Quick update on what is new this week.",
    "video_idea": "standing in a bright modern kitchen, smiling at the camera",
    "resolution": "768P"
  }'
# → { "credits_required": …, "sufficient_credits": true, "lines": [ … ],
#     "price_table_version": "2026-09-30", ... }

# Happy with the price? Fire the same body at /videos, with the quote and a retry key:
#   -H "Idempotency-Key: my-first-video"   and   "expected_credits": <credits_required>
# → { "workflow_id": "partner_h3t_…", "status": "queued", "credits_reserved": …, "warnings": [] }

Poll until it's done, then download

GET /jobs/{workflow_id}/status

curl https://platform.promoat.ai/api/partner/v1/jobs/WORKFLOW_ID/status \
  -H "Authorization: Bearer $PROMOAT_KEY"

# while running → { "status": "running", "phase": "generating", "progress": 40,
#                   "credits_consumed": null, ... }
# when finished → { "status": "completed",
#                   "video_url": "https://…/video.mp4",
#                   "credits_consumed": …, ... }   # never more than reserved

That's the whole loop. The deeper guides cover the two video modes in detail — talking-head and scene videos — plus video edits and how job polling and billing settle.

Try your first call right here

Paste your key in the sidebar, then hit the button — this fires a real (free) request from your browser to this deployment:

Try itGET/api/partner/v1/usage/summaryfree

Add your API key in the sidebar to enable this.

Prefer a raw API explorer?

These guides pair with the Swagger playground — the full OpenAPI spec with try-it-out on every endpoint — and the machine-readable spec at /openapi.yaml.

Building with an AI agent?

Skip the manual integration: install the agent skill — one file that teaches Claude Code (or any agent) every endpoint, price, and playbook in this API, including how to handle your key securely.

Next →What's new in 1.1