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:
- Your server starts a session with your API key.
- Your page shows the recorder in a frame.
- The recorder tells your page what's happening.
- We send the finished video to your webhook.
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
}| Field | Notes |
|---|---|
title | Required, up to 200 characters. Your own label — your users don't see it. |
description | Optional, up to 2,000 characters. |
category | Optional. Sets the interview style: general, educate, promote, story, announce, fundraise, entertain or testimonial. Anything else uses general. |
external_user_id | Optional, 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.comandhttps://yoursite.comare different; so arehttp://localhost:5173andhttp://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 type | What it means |
|---|---|
ready | The recorder loaded. |
recording | Recording started. This counts toward the person's monthly limit. |
uploaded | The footage is saved. You can close the recorder — we finish the video in the background. Has session_id. |
complete | The 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_reached | This 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. |
failed | The 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. |
closed | The 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. Onfailed,erroris currently always "Recording could not be completed". title,descriptionandcategoryare exactly what you sent (an unknown category comes back as you sent it, even though the interview usedgeneral).storyis what we pulled from the interview; any field in it can be null.recording_urlis 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: acompletealways replaces afailed(rarely, a session reported failed recovers when the person retries); afailednever replaces acomplete. Reply 2xx to duplicates. - Test events (from Send a test in your dashboard) look exactly like a real
completeevent, are signed with the same secret, and also have"test": trueand asession_idstarting withtest_. 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_idis 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 }| Response | What to do |
|---|---|
400 | Something in your request body isn't right. The response says what. |
401 | API key missing, wrong or revoked. |
409 monthly_limit_reached | This person used their videos this month. Limits reset on the 1st (UTC). |
429 | More than 10,000 requests today on this key (starting sessions and checking them both count). See the Retry-After header. |
404 | Check a session: no session with that id on your keys. |
- A video counts toward the monthly limit once recording starts.
- Sessions that end
faileddon't count, and neither do links that are never recorded with. - If the person leaves part-way through recording, before the
uploadedmessage (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 showingrecording.
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.