---
title: "Make a walkthrough video from a URL"
method: POST
path: "/renders"
tags: ["renders"]
---

# Make a walkthrough video from a URL

`POST /renders`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/renders`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Work through a live website and turn the recording into a narrated video. Time is RESERVED when it is queued and settled at the finished file's measured length; a failed or cancelled render is charged nothing. This is the tool that records; `renders.quote` prices the same options and starts nothing. Answers 202 with a `Location`; poll until `state` is terminal, then `renders.download`. At most three renders in flight per account.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `background` string: What sits around the recording: `studio` (the default) puts the whole window on a quiet backdrop, `none` lets it fill the frame. Ids from catalog.renderOptions.
  - `captionStyle` string: How burned-in captions look, as an id from `catalog.renderOptions.captionStyles`. It only reaches the frame on a look template that burns captions (`captioned`); on any other template the choice is recorded and nothing is drawn. Omit for the catalogue default.
  - `capture` string: The shape of the recording: a computer window or a phone view.
  - `credentials` object: A demo account to sign in with, and the page it signs in on. Encrypted, used for this render, then deleted.
    - `additionalLoginOrigins` string[]: Other exact https origins this account's sign-in may pass through, e.g. ["https://login.example.com"] for a single sign-on provider on its own host. At most 5. Nothing else — not a redirect, a link or a sibling subdomain — is ever approved on its own: a sign-in that moves to an origin not listed here stops before the account is typed. Ordinary same-origin sign-ins need none.
    - `loginUrl` string, required: REQUIRED whenever credentials are given: the page this demo account signs in on, e.g. https://app.example.com/login. Any origin — a product commonly signs in on a different host from its marketing site, and this is what tells the run where the app itself lives. Must be https; checked by the same guard as the site address. Its origin is the only place the account is typed unless `additionalLoginOrigins` names others.
    - `password` string, required
    - `username` string, required
  - `hint` string, required: What to show, in a sentence: "show the invoice creation flow".
  - `language` string
  - `maxSeconds` integer: The ceiling an Auto video may grow to, 1–600 seconds.
  - `orientation` string
  - `targetSeconds` integer: A fixed length, 1–600 seconds. Omit for Auto, which sizes itself to what it finds and is capped by `maxSeconds`.
  - `templateId` string: A saved or system template id from catalog.renderOptions.
  - `url` string, required: The page to start from. Public addresses only; a private or link-local address is refused.
  - `voiceId` string

## Response `200`

The work was already known — the service recognised this key on its own record and queued nothing new. Answered when the 24-hour idempotency claim has expired but the work has not.

- object
  - `created` boolean, required
  - `resource` object, required
    - `artifactsExpired` boolean, required: The work succeeded but its files were deleted at the end of the retention period.
    - `cancellable` boolean, required
    - `cost` object, required
      - `secondsCharged` number, nullable, required
      - `secondsReserved` number, required
      - `watermark` boolean, required
    - `createdAt` string, date-time, nullable, required
    - `error` object, nullable, required
      - `code` string, required
      - `reason` string, nullable, required
      - `retryable` boolean, required
      - `terminal` boolean, required
    - `expiresAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `id` string, required
    - `idempotencyKey` string, nullable, required
    - `internalStatus` string, required: A finer-grained status word. Informational; branch on `state`.
    - `kind` string, required: walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation
    - `pollAfterMs` number, nullable, required: Wait this long before polling again; null once the state is terminal.
    - `progress` object, nullable, required: HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw.
      - `at` string, nullable, required: When it was reported. A reading that has stopped moving means the work has, not that the bar is broken.
      - `percent` number, required: 0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.
      - `stage` string, required: A short label for the current step. Show it; do not branch on it.
    - `requestId` string, nullable, required
    - `result` object, nullable, required
      - `artifacts` object[], required
        - `bytes` number, nullable, required
        - `expiresAt` string, date-time, nullable, required
        - `sha256` string, nullable, required
        - `type` string, required
        - `url` string, nullable, required
      - `durationSeconds` number, nullable, required
    - `stage` string, nullable, required
    - `startedAt` string, date-time, nullable, required
    - `state` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: The five public states. Poll until one of succeeded/failed/cancelled.

## Other responses

- `202`: The work was queued. Poll the resource at `Location`. A retry with the same Idempotency-Key answers this again, with the same body and the same `Location`, plus `Idempotent-Replayed: true`.
- `400`: `validation_failed` — That request is not valid. · `idempotency_key_required` — This operation needs an Idempotency-Key header: a string of up to 128 characters, unique to this request, so a retry cannot do the work twice. · `hint_required` — Say what to show, in a sentence. · `hint_too_long` — That description of what to show is too long. · `url_invalid` — That address is not one this API will fetch. · `url_private` — That address resolves to a private network and will not be fetched. · `url_malformed` — That address could not be read as a URL. · `login_url_invalid` — That login page address is not one this API will fetch. · `login_url_required` — Credentials need the address of the page they sign in on. · `login_origins_invalid` — Additional sign-in addresses must be a short list of https addresses this API will fetch. · `idempotency_key_unscoped` — An idempotency key needs an account to belong to. · `options_invalid` — Those render options are not valid. · `template_unknown` — No such template. The catalogue is at GET /api/v1/catalog/render-options. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices. · `orientation_unknown` — No such orientation. The catalogue is at GET /api/v1/catalog/render-options. · `capture_unknown` — No such capture shape. The catalogue is at GET /api/v1/catalog/render-options. · `capture_incompatible` — Phone view only makes a portrait video. Pick a portrait orientation or a computer capture. · `avatar_unknown` — No such presenter. The catalogue is at GET /api/v1/catalog/render-options. · `avatar_unavailable` — The presenter circle is not available on this deployment. Make the video without one. · `caption_style_unknown` — No such caption style. The catalogue is at GET /api/v1/catalog/render-options. · `language_unknown` — No such language. The catalogue is at GET /api/v1/catalog/render-options. · `voice_language` — That voice does not speak the chosen language. Pick a voice listed for it. · `background_unknown` — No such background. The catalogue is at GET /api/v1/catalog/render-options. · `length_below_minimum` — That length is shorter than a walkthrough can be. · `site_not_allowed` — This website can't be used: public platforms and sensitive-topic sites aren't allowed. If you think this is a mistake, write to support@gogoscreen.com or use "Talk to a person": support can allow a site by name.
- `401`: `unauthorized` — Authentication is required.
- `402`: `insufficient_seconds` — You do not have enough video time left. Buy more time to keep going.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs.
- `404`: `not_found` — No such resource.
- `409`: `idempotency_conflict` — That idempotency key was already used with a different request. · `idempotency_in_progress` — That idempotency key is still being processed. · `conflict` — That request conflicts with the current state. · `too_many_in_flight` — Too many operations are already running on this account.
- `413`: `payload_too_large` — That request body is too large.
- `415`: `unsupported_media_type` — That content type is not supported.
- `429`: `rate_limited` — Too many requests. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.
- `503`: `queue_unavailable` — That work cannot be queued right now. Try again shortly. · `vault_unavailable` — Credentials cannot be stored right now. Try again shortly. · `wallet_unavailable` — Video time cannot be reserved right now. Try again shortly.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)