Skip to content

catalog.renderOptions

The walkthrough render options

GET/catalog/render-options

Operation
catalog.renderOptions
MCP tool
catalog_renderOptions

Every choice a walkthrough render accepts: the look templates, the voices, the orientations, the capture sizes (with the pixel size each records at), the length presets, the languages, the backgrounds, and the caption styles (each with the style block it is drawn from, so a client can show a faithful sample). The ids here are the ids renders.create and storyboards.create take. avatars is present and EMPTY while the presenter circle is switched off on this deployment; an avatarId is not a field those operations take then.

curl 'https://api.gogoscreen.com/api/v1/catalog/render-options' \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY"
A request to this operation.
json
{
  "templates": [
    {
      "id": "standard",
      "name": "Standard",
      "description": "The default look. Moderate pacing, a steady full-frame view, no captions.",
      "isDefault": true
    },
    {
      "id": "captioned",
      "name": "Captioned",
      "description": "The standard look with captions burned in, for feeds that play muted.",
      "isDefault": false
    }
  ],
  "voices": [
    {
      "id": "sarah",
      "name": "Sarah",
      "description": "English (US). Female, clear and confident, a presenter's pace. Also reads Spanish, Portuguese, French, German and Italian.",
      "isDefault": true,
      "languages": [
        "en",
        "es"
      ],
      "gender": "female"
    },
    {
      "id": "george",
      "name": "George",
      "description": "English (UK). Male, warm and measured, a storyteller's read. Also reads Spanish, Portuguese, French, German and Italian.",
      "isDefault": false,
      "languages": [
        "en",
        "es"
      ],
      "gender": "male"
    }
  ],
  "orientations": [
    {
      "id": "landscape",
      "name": "Landscape",
      "description": "16:9. For a website, a docs page or an email.",
      "isDefault": true,
      "width": 1440,
      "height": 810
    },
    {
      "id": "portrait",
      "name": "Portrait",
      "description": "9:16. For Shorts, Reels and TikTok, which crop a landscape frame badly.",
      "isDefault": false,
      "width": 1080,
      "height": 1920
    }
  ],
  "captures": [
    {
      "id": "desktop",
      "name": "Computer view",
      "description": "The app as it looks on a laptop. Works on any app.",
      "isDefault": true,
      "viewport": {
        "width": 1440,
        "height": 810
      }
    },
    {
      "id": "desktop-tall",
      "name": "Spacious computer view",
      "description": "More room for dashboards and longer forms.",
      "isDefault": false,
      "viewport": {
        "width": 1440,
        "height": 1080
      }
    }
  ],
  "avatars": [],
  "lengths": [
    {
      "key": "30",
      "seconds": 30,
      "narration": true
    },
    {
      "key": "45",
      "seconds": 45,
      "narration": true
    }
  ],
  "minTargetSeconds": 30,
  "autoMaxSeconds": {
    "min": 30,
    "max": 300,
    "default": 300
  },
  "languages": [
    {
      "id": "en",
      "name": "English",
      "nativeName": "English",
      "isDefault": true
    },
    {
      "id": "es",
      "name": "Spanish",
      "nativeName": "Español",
      "isDefault": false
    }
  ],
  "backgrounds": [
    {
      "id": "none",
      "name": "Full frame",
      "description": "The recording fills the whole frame.",
      "isDefault": false
    },
    {
      "id": "studio",
      "name": "Studio",
      "description": "The app sits on a soft, quiet backdrop with a shadow, the whole window in view.",
      "isDefault": true
    }
  ],
  "captionStyles": [
    {
      "id": "clean",
      "name": "Clean",
      "description": "White text with a soft shadow. Reads over almost anything and adds no furniture to the frame.",
      "isDefault": true,
      "look": {
        "fontFamily": "Inter",
        "fontSizePct": 7,
        "weight": 800,
        "color": "#FFFFFF",
        "style": "shadow",
        "uppercase": false,
        "maxWords": 3,
        "safeBottomPct": 17,
        "maxWidthPct": 80
      }
    },
    {
      "id": "boxed",
      "name": "Boxed",
      "description": "White text on a dark slab. The one style that still reads over a white screen, which a screen recording very often is.",
      "isDefault": false,
      "look": {
        "fontFamily": "Inter",
        "fontSizePct": 6.4,
        "weight": 800,
        "color": "#FFFFFF",
        "boxColor": "#141413",
        "style": "box",
        "uppercase": false,
        "maxWords": 3,
        "safeBottomPct": 17,
        "maxWidthPct": 78
      }
    }
  ]
}
200 response, captured from a real call. Ids, timestamps and signed URLs are replaced; the shape is untouched.

At a glance

FactDetail
Scopescatalog:read
Credentialsa signed in dashboard session or an API key.
Rate limit600 requests a minute per credential, in the read class.
IdempotencyNot applicable. This operation changes nothing.
MCP toolcatalog_renderOptions
Always setsCache-Control: public, max-age=300

Response

Answers 200. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

The walkthrough render options

200 OK body
NameTypeDescription
autoMaxSecondsobject
defaultnumber
maxnumber
minnumber
avatarsobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
backgroundsobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
captionStylesobject[]How burned-in captions look, for the look templates that burn them. Each row carries look, the style block the captions are actually drawn with.
descriptionstring | null
idstring
isDefaultboolean
namestring
capturesobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
languagesobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
lengthsobject[]
keystring
narrationboolean
secondsnumber | null
minTargetSecondsnumber
orientationsobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
templatesobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
voicesobject[]
descriptionstring | null
idstring
isDefaultboolean
namestring
200 OK headers
HeaderMeaning
Cache-ControlAlways public, max-age=300.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

CodeStatusWhen it happensWhat to do
validation_failed400The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.Read details.issues. Each entry carries a path, a message and a machine readable code. Fix every named field and send the request again; the same body always fails the same way.
unauthorized401No credential was presented, or the key is unknown, revoked or expired, or an X-API-Key header carried something that is not an API key. details.reason says which.Send Authorization: Bearer gsk_live_…. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in Authorization, never in X-API-Key.
forbidden_scope403The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. keys.* and assistant.* are user only and can never be called by a key.details.requiredScopes and details.missingScopes name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When details.allowedActors is present, no key can call this operation at all.
not_found404No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.Check the id. Do not treat this as a permissions problem.
rate_limited429The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. details.scope is minute, day or account, or global when the product's own daily cap on voice previews is spent.Wait the Retry-After seconds and retry. details.limit and details.resetAt say what was hit and when it reopens. The RateLimit-* headers on every answer let a client pace itself before it gets here.
internal_error500An unhandled failure inside this API. The original message is logged and never answered.Retry once, then quote requestId to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.