Chitrio API v1

Create a key in the app under Settings, then API keys, keep it in an environment variable on your server, and run the three calls below.

# 0) Optional: price it and check the balance
curl "https://chitrio.com/api/v1/estimate?durationInMinutes=3&generateShort=true" -H "X-Api-Key: $CHITRIO_KEY"
curl https://chitrio.com/api/v1/balance -H "X-Api-Key: $CHITRIO_KEY"

# 1) Start a video (webhookUrl is optional)
curl -X POST https://chitrio.com/api/v1/videos \
  -H "X-Api-Key: $CHITRIO_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"How the fastest trains work","durationInMinutes":3,"language":"en","generateShort":true,
       "webhookUrl":"https://your-server.com/chitrio/webhook"}'
# -> { "jobId": "JOB_ID", "status": "Processing", "title": "..." }

# 2) Wait for the webhook, or poll every 15 to 30 seconds
curl https://chitrio.com/api/v1/videos/JOB_ID -H "X-Api-Key: $CHITRIO_KEY"

# 3) Download with the same key (-L follows the redirect)
curl -L https://chitrio.com/api/v1/videos/JOB_ID/download -H "X-Api-Key: $CHITRIO_KEY" -o video.mp4
curl -L "https://chitrio.com/api/v1/videos/JOB_ID/download?variant=short" -H "X-Api-Key: $CHITRIO_KEY" -o short.mp4

Send the workspace's key with every request:

X-Api-Key: yta_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tools that can only attach a Bearer token can send Authorization: Bearer yta_live_... instead. A key is shown once when it is created (Chitrio keeps only a hash), and workspace admins can create several and revoke any of them at any time.

A key acts on one workspace: its plan, credit balance, voice, brand settings and connected YouTube channel apply to every call made with it.

Upload a product walkthrough or tutorial recording. Chitrio splits it into scene-length segments, transcribes each one, and then builds a narrated, captioned video on top of your footage, in order.

{
  "recordingId": "b7d0e6c2a4f94d3b9a1e0c5d7f2a8b61",
  "expiresAtUtc": "2026-10-03T10:12:44Z",
  "segments": [
    { "index": 0, "start": 0, "duration": 25, "transcript": "So first we open the products page" },
    { "index": 1, "start": 25, "duration": 21.4, "transcript": null }
  ]
}

# 1) Upload the recording (mp4 / mov / webm / m4v, up to 100 MB)
curl -X POST https://chitrio.com/api/v1/recordings \
  -H "X-Api-Key: $CHITRIO_KEY" -F [email protected] -F sceneSeconds=25
# -> { "recordingId": "REC_ID", "segments": [ { "index": 0, "start": 0, "duration": 25, "transcript": "..." } ] }

# 2) Make the video. Notes say what is on screen; a silent recording needs them.
curl -X POST https://chitrio.com/api/v1/videos/from-recording \
  -H "X-Api-Key: $CHITRIO_KEY" -H "Content-Type: application/json" \
  -d '{"recordingId":"REC_ID","topic":"How to add a product",
       "notes":[{"t":2,"text":"Open the Products page"},{"t":30,"text":"Fill in the price and save"}]}'
# -> { "jobId": "JOB_ID", "status": "Processing", "title": "...", "scenes": 3 }  then poll or wait for the webhook

Instead of polling, Chitrio can POST a signed event to your server when a job completes or fails.

• Workspace default: Settings, then API keys, then Webhooks. Save an https URL and every job started through this API reports to it. Test sends a signed webhook.test event right away, and Recent deliveries shows each event, its HTTP result and attempts.
• Per job: send webhookUrl with the request. It wins over the workspace default for that job.
• Signing secret: in the same place (whsec_...; admins can reveal or rotate it). Every delivery is signed with the workspace's secret.
• URL rules: https only, no credentials in the URL, and the host must resolve to a public internet address. Redirects are not followed.

POST https://your-server.com/chitrio/webhook
Content-Type: application/json
User-Agent: Chitrio-Webhooks/1.0
X-Chitrio-Event: video.completed
X-Chitrio-Delivery: 5b0e1f2a9c7d4e3f8a6b1c2d3e4f5a6b
X-Chitrio-Signature: t=1790791417,v1=ad4f3d52abcd4c98813782823e92e0a5a52f49bdb0c490834e5f86bfe90eccc2

{
  "event": "video.completed",
  "deliveryId": "5b0e1f2a9c7d4e3f8a6b1c2d3e4f5a6b",
  "jobId": "3f1c9a0e-...",
  "status": "Completed",
  "videoUrl": "https://chitrio.com/api/v1/videos/3f1c9a0e-.../download",
  "shortUrl": null,
  "error": null,
  "occurredAtUtc": "2026-09-30T10:19:05Z"
}

Delivery and retries

• Answer with any 2xx within 10 seconds, and do the real work after answering.
• Anything else (a non-2xx, a timeout, a connection error) is retried 3 times: after about 30 seconds, 2 minutes and 10 minutes. After that the delivery is marked failed in the log; the job is unaffected and the status endpoint still has the result.
• Delivery is at least once, so the same event can arrive twice. Deduplicate on deliveryId.

Verifying the signature

X-Chitrio-Signature: t=<unix seconds>,v1=<hex>

v1 = hex( HMAC-SHA256( key     = your whole secret string, including "whsec_",
                       message = "<t>.<raw request body>" ) )

1. Read the raw body bytes before any JSON parsing; re-serialising changes the bytes and breaks the check.
2. Recompute v1 and compare in constant time.
3. Reject a t more than 5 minutes from your clock (replay protection).

// Node.js + Express
import crypto from "node:crypto";
import express from "express";

function verifyChitrio(rawBody, header, secret, toleranceSeconds = 300) {
  const fields = {};
  for (const part of (header || "").split(",")) {
    const i = part.indexOf("=");
    if (i > 0) fields[part.slice(0, i).trim()] = part.slice(i + 1).trim();
  }
  const t = fields.t;
  if (!t || !/^\d+$/.test(t) || !fields.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(fields.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
app.post("/chitrio/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyChitrio(raw, req.get("X-Chitrio-Signature"), process.env.CHITRIO_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(raw);
  // Deduplicate on event.deliveryId, then queue your work for event.jobId.
  res.sendStatus(200);
});
app.listen(3000);

Rotating the secret: rotate in Settings, then update your server promptly. Deliveries are signed with the new secret from the moment you rotate.

Errors carry a JSON body { "error": "readable message" }. Nothing is charged for a refused request. A rate-limit 429 also carries a Retry-After header and retryAfterSeconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 412
Content-Type: application/json

{ "error": "Rate limit reached. Retry after 412 seconds.", "retryAfterSeconds": 412 }

• Starting work (creating a video, uploading a recording, creating from a recording): 20 requests per 10 minutes per API key. Over it: 429 with Retry-After.
• Concurrent renders: up to 3 videos per workspace render at once. Another start answers 429 until one finishes.
• Duplicate guard: sending the identical request again within about 90 seconds, while the first is still running, answers 409. A different language, style or length is a new video and is always allowed.
• Status, list, download, estimate, balance and cancel calls are not rate limited.

These are defaults and can change. Treat any 429 or 503 as "retry later" with exponential backoff, for example 30, 60, then 120 seconds, and honour Retry-After when present.

Every render uses the workspace's credits, exactly as a render started in the app does. The cost depends on the video (its length, whether a Short is made, and so on). GET /api/v1/estimate returns it before you start, GET /api/v1/balance returns the balance, and the pricing page lists the plans.

Credits are taken when the render starts and returned automatically if it fails or is cancelled. If the balance is short of what full AI motion would cost, the video still renders with motion fitted to the balance instead of failing. A 402 means there is not enough for any render at all.

Pass one of these codes as language. The script, narration, captions and on-screen text all come out in that language, in its own script.

Voice and branding (narrator voice, caption style, brand colour, video quality) come from the workspace's settings in the app. Set them once; every API render follows them.

Formats: the main video is a 16:9 MP4. generateShort: true adds a 9:16 vertical cut of up to 60 seconds with captions, ready for Shorts, Reels and Status. Every scene is animated with AI motion; there is nothing to configure.

Webhooks are the better fit for production. If you poll:

• A short video takes a few minutes; long videos and busy periods take longer.
• Poll the job every 15 to 30 seconds and stop when status is no longer Processing.
• Set your own ceiling (for example 60 minutes) and alert on it rather than polling forever.
• Store the job id. You can come back to it any time, and the list endpoint shows recent jobs.

• Keys are secrets. Use them on your server only, never in a browser, a mobile app or a public repository.
• Use one key per integration and environment, so one can be revoked without touching the others.
• Rotate by creating a new key, deploying it, then revoking the old one. Settings shows each key's prefix and when it was last used.
• The video links need the key. To give files to your own users, download them and serve them from your storage.
• A key only ever sees its own workspace; another workspace's job id answers 404.
• Verify every webhook's signature and timestamp before trusting it, and keep the signing secret on your server.
• autoUpload publishes to a real YouTube channel. Use autoUploadPrivacy: "private" while integrating.
• Report a vulnerability to [email protected] with "SECURITY" in the subject.

Available on request. Tell us which one you need first.