Personade API

There are no webhooks

Not yet, and it is better to say so here than to let you find out after you have built around one. Nothing calls you back when a video finishes. You poll.

Practically, this matters less than it sounds, for two reasons. A campaign of forty finishes in a few minutes. And the link does not wait for the video: a person's page URL is returned the moment they are added, shows a personalized holding screen until the render lands, then becomes the video at the same URL.

How to poll

For one person, call GET /v1/leads/{id} with the id you got when you added them, and read videoReady. For a whole campaign, call GET /campaigns/{id} every 30 seconds while it is generating. That is comfortably inside the rate limit even with several campaigns running, and renders take a minute or two each, so anything faster only burns your allowance.

 while :; do$  status=$(curl -s https://app.personade.com/api/v1/campaigns/$ID \     -H "Authorization: Bearer $PERSONADE_KEY")$  echo "$status" | grep -q '"pending":0' && echo "$status" | grep -q '"rendering":0' && break$  sleep 30$done$curl -s https://app.personade.com/api/v1/campaigns/$ID/videos \   -H "Authorization: Bearer $PERSONADE_KEY"

Stop when counts.pending and counts.rendering are both zero. Do not wait for delivered: a campaign where one video failed settles on partial_done and never reaches it, so a loop waiting for delivered runs forever.

Statuses

A campaign is in exactly one of these.

Every person in a campaign is counted under one of these in counts.

Render stages

stages breaks down what the in-flight videos are doing right now. Useful for a progress line, not for logic: a video passes through all of these and the shape of the object changes constantly.

When it stalls

If our side stops moving, stalled appears on the status reply. It carries how many minutes it has been quiet, how many jobs are stuck, and a sentence you can show a person.

{
  "id": "3b7e5a12-9c04-4f2a-b6d1-77e8c9a0f4b2",
  "status": "rendering",
  "counts": { "total": 40, "pending": 0, "rendering": 12, "complete": 28,
              "failed": 0, "cancelled": 0, "skipped": 0 },
  "stages": { "lipsync": 12 },
  "stalled": {
    "minutes": 18,
    "jobs": 12,
    "message": "12 videos stopped reporting progress 18 minutes ago. This is our end, not anything anyone did. Nothing extra has been charged, and the videos resume on their own once it recovers. Do not approve again - that would charge twice."
  }
}