RecordHTML API

Send real requests with one of your keys and see the answer, with the same request as code beside it. An estimate records nothing; a recording started here is a real one, in your recordings and within your limits.

The body of POST /v1/jobs is the same as the recorder form in the web app. Only url, width, height and durationSec are required; unknown fields are refused.

Timing, Sync modes and trim_start() / trim_end() markers

POST /v1/jobs/estimate takes the same body and answers with ok, the problems it found (invalidIssues, limitIssues), the time and resources the recording would take, and the renderer it would run on.

Add these calls to the creative's JavaScript, not to your API client. The recorder supplies both functions before the page's scripts run, including in iframes. No SDK is needed. The guards below let the same creative run normally outside the recorder.

• trim_start() marks the beginning of the content to keep. Call it once when your assets are ready, just before starting the animation.
• trim_end() marks the end of the content to keep. Call it once from the animation's completion callback, after displaying the final frame and before resetting or looping.

// In your creative, after assets are ready and just before playback:
if (typeof window.trim_start === 'function') window.trim_start();
// Start your animation here.

// In your animation's completion callback, after its final frame:
if (typeof window.trim_end === 'function') window.trim_end();

Do not paste the two calls next to each other and run them together: that marks an empty clip. These functions signal timing; they do not start, stop or wait for your animation. Connect them to your own playback and completion code.

markerWaitSec is how long to wait for trim_start() after page load: 0–60 seconds, default 10. It is not padding added to the output. In Auto, a missing start marker falls back to the original page-load time, not the end of the wait. The first eligible start marker is used; repeated or late start calls do not restart the clip.

startAt is an offset in milliseconds from the selected start: the marker when used, otherwise page load. Omit it or use "load" for no offset. In the form this is Start → After a delay.durationSec is the output length, or the maximum length when an earlier valid trim_end() shortens it. An end marker before the selected start is ignored. Without an end marker, recording uses the full duration; Require markers only requires the start marker.

markerLatencyMs is an advanced 0–1000 ms override for the delay between JavaScript executing and the corresponding visual change reaching a captured frame. Leave it unset (blank in the form) to use the recorder's automatic measurement. It is neither a readiness timeout nor an intentional start delay.

{
  "url": "https://example.com/banner/",
  "width": 300,
  "height": 600,
  "durationSec": 15,
  "sync": "markers",
  "markerWaitSec": 10
}

Example: the page loads, prepares assets for 3 seconds, calls trim_start(), plays a 5-second animation, then calls trim_end(). With the request above and no start delay, the output is about 5 seconds: the loader is excluded, and the 15-second duration is only a cap. Without trim_end(), it keeps 15 seconds from the start marker.

Every endpoint returns jobs in the same shape: id, status, progress, createdAt, finishedAt, request (what you sent), error, report (codec, size, frame rate, duration, warnings), video, renderer (cpu or gpu: where it records, which is how auto resolved; null until the recording service accepts the job) and pageUrl (the recording's page in the web app, for a person to open; they sign in). New fields may be added; existing ones won't change.

video is set once the job is ready. Lists leave video.url empty; a single job carries a signed link valid for one hour, and /video always redirects to a fresh one.

Send an Idempotency-Key header with POST /v1/jobs (any printable text up to 255 characters, such as your own id for the creative version). Repeating the request with the same key returns the job it created, with the header idempotent-replayed: true, instead of recording again. Reusing a key for a different body answers 409 idempotency_conflict. If the request failed before the recording service accepted it (a 5xx answer), retry with the same key: it records then.

Errors are JSON: { "error": "code", "message": "…" }, plus issues (path, message) for invalid fields or reasons for capacity.

The API and the web app share your account's limits: recordings in progress at a time, recordings per 24 hours, and the maximum duration, size and frame rate. On top of that, each account can make 300 API requests a minute, start 20 recordings a minute and request 60 estimates a minute.