GueauxStudioDevelopers

Add the GueauxStudio recorder to your site

Your users record an interview-style video with an AI host, right inside your app. You get the finished, edited video back. Four steps:

  1. Your server starts a session with your API key.
  2. Your page shows the recorder in a frame.
  3. The recorder tells your page what's happening.
  4. We send the finished video to your webhook.
Before you start: in your partner dashboard, create an API key, add your website, and add your webhook URL. No access yet? Request it here.

1. Start a session

Call this from your server, never from the browser — it uses your secret API key. Start a new session each time a user opens the recorder. Send your own ID for the user so your monthly limit can be applied per person.

POST https://gueauxstudio.com/api/public/v1/session
Authorization: Bearer gxs_live_…
Content-Type: application/json

{
  "title": "My story",
  "description": "Optional",
  "category": "fundraise",
  "external_user_id": "user_123"
}

Response (201):

{
  "session_id": "6f1c…",
  "session_url": "https://gueauxstudio.com/embed/6f1c…?sig=…",
  "status": "pending",
  "created_at": "2026-11-08T12:00:00Z",
  "monthly_limit": 2,     // only when you send external_user_id
  "monthly_used": 0       //   and have a monthly limit set
}
FieldNotes
titleRequired, up to 200 characters. Your own label — your users don't see it.
descriptionOptional, up to 2,000 characters.
categoryOptional. Sets the interview style: general, educate, promote, story, announce, fundraise, entertain or testimonial. Anything else uses general.
external_user_idOptional, up to 200 characters. Your ID for the person recording. Needed for the per-person monthly limit (set in your dashboard), and sent back in the webhook. Without it, no per-person limit applies.
  • Create the session when the person taps record, not on page load. Disable your button until it comes back so a double tap doesn't make two.
  • A link doesn't expire until someone records with it. Opening the recorder and closing it before recording doesn't use it up — the same link works again. A link nobody records with costs nothing, doesn't count toward any limit, and never sends a webhook.

2. Show the recorder

Put session_url in a full-screen frame on one of the websites you listed in your dashboard. The allow line is required — without it the camera and microphone won't start.

<iframe
  src="SESSION_URL"
  allow="camera; microphone; autoplay; fullscreen"
  style="position:fixed; inset:0; width:100%; height:100%; border:0">
</iframe>
  • Your users don't need a GueauxStudio account.
  • Each link is for one recording. Make a new session for the next one.
  • The recorder shows your logo and button colors from the dashboard.
  • Don't add referrerpolicy="no-referrer" to the frame — some browsers use the referrer to confirm your website.
  • Keep your own close button on top of the frame so people can always get out. Removing the frame is how you close the recorder — your page can't send it commands.
  • Websites must match exactly what you listed: scheme, host and port (https://www.yoursite.com and https://yoursite.com are different; so are http://localhost:5173 and http://localhost:3000). No wildcards. On a site that isn't listed, the recorder shows "This recorder isn't set up for this website yet".

3. Listen for messages

The recorder tells your page what's happening with postMessage, so you can close it or move your user along. Only trust messages from https://gueauxstudio.com.

window.addEventListener("message", (e) => {
  if (e.origin !== "https://gueauxstudio.com") return;
  if (e.data?.source !== "gueauxstudio") return;

  switch (e.data.type) {
    case "uploaded":      // footage saved — safe to close and move on
    case "closed":        // the person chose to leave
      closeRecorder();
      break;
    case "limit_reached": // used up this month's videos
      closeRecorder();
      showLimitMessage();
      break;
    case "failed":        // can't continue — see e.data.reason
      closeRecorder();
      showErrorMessage(e.data.reason);
      break;
  }
});
Message typeWhat it means
readyThe recorder loaded.
recordingRecording started. This counts toward the person's monthly limit.
uploadedThe footage is saved. You can close the recorder — we finish the video in the background. Has session_id.
completeThe video is ready. Only sent if the recorder is still open; the webhook always comes. Has session_id, plus title and description pulled from the interview (same as the webhook's story.title / story.description).
limit_reachedThis person has used their videos for the month. Starting a session already returns 409 in that case; this one covers links made earlier that are used after the limit was hit — we check again right before recording.
failedThe session can't continue. Has reason: invalid_link, session_closed or already_recorded (that link was already used — make a new session), insufficient_credits (your account is out of credits — see Credits below), editing_unavailable (video editing is briefly down — try again in a few minutes), or server_error / another code. session_closed means that session already finished or failed. For the "try again" cases, opening the same link again is fine as long as nobody recorded with it; if it fails again, start a new session.
closedThe person chose to leave.

Messages are for your screens only. Decide what to save from the webhook, which is signed.

4. Get the finished video

Usually a few minutes after recording, we POST to your webhook URL. Once the footage has uploaded (the uploaded message), a webhook always comes — complete, or failed if we couldn't turn it into a video. Use story to fill in your own form.

{
  "session_id": "6f1c…",
  "status": "complete",              // or "failed"
  "recording_url": "https://…mp4",   // null when failed
  "title": "My story",               // what you sent
  "description": null,
  "category": "fundraise",
  "external_user_id": "user_123",
  "story": {                         // pulled from the interview; null when failed
    "title": "…",
    "description": "…",
    "goal": "…",
    "amount": "…",
    "best_quote": "…",
    "transcript": "…",
    "duration_sec": 212
  },
  "error": null,                     // a short reason when failed
  "completed_at": "2026-11-08T12:09:00Z"
}
  • There's one kind of event; tell success from failure by status. On failed, error is currently always "Recording could not be completed".
  • title, description and category are exactly what you sent (an unknown category comes back as you sent it, even though the interview used general). story is what we pulled from the interview; any field in it can be null.
  • recording_url is a public link (no login needed). Download your own copy as soon as you get it — don't rely on our link forever.
  • Headers: Content-Type: application/json, User-Agent: GueauxStudio-Webhook/1.0. We don't send from fixed IP addresses, so check the signature instead.

Check it's really from us

Every webhook has an X-Gueaux-Signature: sha256=… header: an HMAC-SHA256 of the raw request body, using the signing secret from your dashboard, as lowercase hex. Check it before trusting anything. Reply with any 2xx once you've saved it — anything else (or no reply within 10 seconds) and we try again — 5 tries in all, over about half an hour. After that, use Check a session.

import crypto from "node:crypto";

// rawBody = the exact bytes we sent (read it before parsing JSON)
function isFromGueauxStudio(rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.GUEAUXSTUDIO_WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
  • Save by session_id, and you may get the same webhook more than once. The rule: a complete always replaces a failed (rarely, a session reported failed recovers when the person retries); a failed never replaces a complete. Reply 2xx to duplicates.
  • Test events (from Send a test in your dashboard) look exactly like a real complete event, are signed with the same secret, and also have "test": true and a session_id starting with test_. Check the signature, don't save it, and reply 2xx — the dashboard shows what your server replied.
  • Replacing the signing secret in the dashboard takes effect right away — there's no overlap where both work. Update your server straight after; any webhook it rejects in between is retried.
  • We don't sign a timestamp, so there's no time window to check — saving by session_id is what stops replays from doing harm.

Limits and errors

Every error is JSON with an error field, e.g. { "error": "Invalid or revoked API key" }. The 409 also carries the counts:

{ "error": "monthly_limit_reached", "monthly_limit": 2, "monthly_used": 2 }
ResponseWhat to do
400Something in your request body isn't right. The response says what.
401API key missing, wrong or revoked.
409 monthly_limit_reachedThis person used their videos this month. Limits reset on the 1st (UTC).
429More than 10,000 requests today on this key (starting sessions and checking them both count). See the Retry-After header.
404Check a session: no session with that id on your keys.
  • A video counts toward the monthly limit once recording starts.
  • Sessions that end failed don't count, and neither do links that are never recorded with.
  • If the person leaves part-way through recording, before the uploaded message (or you remove the frame then), it counts as used and there's no video. You won't get a webhook, and Check a session keeps showing recording.

Credits

Videos are paid for by your GueauxStudio account: each recording uses 1,000 credits when it starts, unless your account is on an unlimited plan. Check and buy credits, or change plan, on your account's Billing page.

Starting a session still works when you're out of credits — the recorder sends failed with reason insufficient_credits right before recording, and nothing is used.

Check a session

If you missed a webhook, ask for a session any time.

GET https://gueauxstudio.com/api/public/v1/session/SESSION_ID
Authorization: Bearer gxs_live_…

→ { "session_id": "6f1c…", "id": "6f1c…", "status": "complete",
    "recording_url": "https://…mp4", "title": "…", "description": null,
    "category": "fundraise", "external_user_id": "user_123",
    "story": { …same as the webhook… }, "error": null,
    "created_at": "…", "updated_at": "…" }

status is one of pending (not recorded yet), recording, complete or failed. story is filled in once the session is complete, so this gives you everything a missed webhook would have; updated_at is when it finished.

Testing

  • Use Send a test in your dashboard to check your webhook and signature check.
  • Use Open a test recording to try the recorder with your branding — it opens in a new tab, and the finished video comes to your webhook like a real one (no external_user_id, so no per-person limit).
  • There's no separate sandbox: test recordings are real recordings and use your account's credits like any other.
  • Testing on a preview or local site? Add its address under Your websites (http://localhost is allowed).
  • Test on an iPhone in Safari — that's where camera access is strictest.