Developers

API Documentation

This is the same API the official Zapier integration is built on.

Authentication

Every request needs your API key as a bearer token. Find your key at Settings once you're signed in - it's shown at the top of that page, with a button to generate a new one if it's ever compromised.

Authorization: Bearer <your_api_key>

A missing or invalid key returns 401:

{"error": "Invalid or missing API key"}

Verify your key

GET /api/me.php

Returns the account tied to your key. Useful for confirming a key works before using it elsewhere.

curl https://voicereel.chriscastle.com/api/me.php \
  -H "Authorization: Bearer <your_api_key>"

{
  "email": "[email protected]",
  "plan": "free",
  "credits_used": 3,
  "credits_limit": 10
}

Generate a video

POST /webhook/zapier.php

Submit text or an audio URL. The video renders against your account's currently-selected avatar (set at Settings - there's no per-request override). Returns immediately with the job's id and share link; the video itself renders in the background, so video_url is null until it's done.

Body parameters

Field	Type	Notes
text	string	Provide this or audio_url, not both.
audio_url	string	A public HTTPS URL to an audio file (mp3, m4a, mp4, wav, webm, ogg) - transcribed automatically before rendering.
webhook_url	string, optional	If set, VoiceReel POSTs the finished job (same shape as the response below) to this URL once rendering completes.

curl -X POST https://voicereel.chriscastle.com/webhook/zapier.php \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Quick update on the Q3 numbers..."}'

{
  "id": "142",
  "status": "pending",
  "share_url": "https://voicereel.chriscastle.com/v/ab12cd34ef56",
  "video_url": null,
  "created_at": "2026-07-12T18:03:11+00:00"
}

Error responses

Status	Meaning
405	Anything other than POST.
422	Neither text nor audio_url was provided, or your account has no avatar selected yet.
402	No credits remaining.

List your videos

GET /api/jobs.php

Returns your jobs, newest first by default.

Query param	Notes
status	Optional filter, e.g. done, rendering, failed.
sort	asc or desc (default).

curl "https://voicereel.chriscastle.com/api/jobs.php?status=done&sort=desc" \
  -H "Authorization: Bearer <your_api_key>"

[
  {
    "id": "142",
    "status": "done",
    "share_url": "https://voicereel.chriscastle.com/v/ab12cd34ef56",
    "video_url": "https://voicereel.chriscastle.com/videos/ab12cd34ef56.mp4",
    "created_at": "2026-07-12T18:03:11+00:00"
  }
]

Check a single video's status

GET /api/job_status.php?id={id}

Same shape as one item from the list endpoint above.

curl "https://voicereel.chriscastle.com/api/job_status.php?id=142" \
  -H "Authorization: Bearer <your_api_key>"

Status	Meaning
422	id is missing or not numeric.
404	No job with that id, or it doesn't belong to your account.

Job statuses

A job moves through these statuses in order; transcribing is skipped for text-only jobs.

Status	Meaning
pending	Queued, not yet picked up.
transcribing	Audio is being transcribed (audio jobs only).
scripting	The transcript/text is being tightened into a video script.
rendering	The avatar video is being generated.
done	video_url is now populated and permanent.
failed	Something went wrong - no credit was charged.

Rate limits and credits

Each successfully rendered video uses one credit from your plan. There's no separate API rate limit beyond your account's credit balance - see pricing for credit packs and plans.