Overview & quickstart

Promoat Partner API

Generate AI presenter videos from your own backend: create a character, clone a voice, and queue talking-head or multiscene videos. 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, or pick a free ready-made library voice by language.
TTS & first-frame images — speech audio and still frames as standalone outputs.
Videos — the headline act: a single-shot talking-head video, or a multi-scene video where the character acts the script out across scenes.

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

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 — 10 credits

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": 10 }

Get a voice (free library pick, or clone a real one)

POST /voices — free by language, or 30 credits to clone

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", "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": "480p"
  }'
# → { "credits_required": 175, "sufficient_credits": true, ... }

# Happy with the price? Fire the same body at /videos:
# → { "workflow_id": "partner_thv_…", "status": "queued", "credits_reserved": 175 }

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", "credits_consumed": null, ... }
# when finished → { "status": "completed",
#                   "video_url": "https://…/video.mp4",
#                   "credits_consumed": 170, ... }

That's the whole loop. The deeper guides cover the two video modes in detail — talking-head and multi-scene — plus 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 →Authentication