GogoScreen Voices API

openapi: 3.2.0
info:
  contact:
    email: support@gogoscreen.com
    name: GogoScreen support
    url: https://gogoscreen.com/support
  description: 'Every operation is defined once, and this document and the MCP tool list are both built from that one definition, so they cannot disagree.


    **Authentication.** `Authorization: Bearer gsk_…` (an API key) or `X-API-Key: gsk_…`. A dashboard session token in the same Bearer header is accepted so the dashboard''s developer console can call this API with the session it already has.


    **Pagination.** Cursor only. Pass `limit` (1–100, default 20) and the previous page''s `nextCursor`; a null `nextCursor` is the end of the walk. Cursors are opaque — do not build one.


    **Errors.** Every non-2xx answers `{ error: { code, message, details?, requestId } }`. Branch on `code`; quote `requestId` when reporting a failure.


    **Rate limits.** Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds). Each operation belongs to a class — read 600/min, write 120/min, expensive 20/min, charge 20/min — counted per credential, and a key may carry a lower per-minute or per-day limit of its own. Above those there is one ceiling per ACCOUNT, shared by every key and every class, so holding more keys does not raise what an account can do. A refusal is `429 rate_limited` with `Retry-After` and `details.scope` naming which ceiling it was: `minute`, `day` or `account`.


    **Long work.** Renders, storyboards, scans, generations and exports are jobs: they answer a resource with a `state` of queued/running/succeeded/failed/cancelled and a `pollAfterMs`. Poll until the state is terminal, or subscribe to a webhook.


    **Idempotency.** Every mutating operation takes an `Idempotency-Key` header; a replay with the same body returns the stored response.


    **Webhooks.** Register an endpoint with `POST /webhooks` and you are told when work finishes instead of polling for it. The secret is returned once, at registration.


    Every delivery is a `POST` of a `WebhookEvent` with these headers: `Gogoscreen-Event-Id`, `Gogoscreen-Event-Type`, `Gogoscreen-Delivery-Id`, `Gogoscreen-Delivery-Attempt` and `Gogoscreen-Signature`.


    The signature is `t=,v1=`, where the hex is `HMAC-SHA256(secret, "." + rawBody)`. **Verify it against the RAW body you received**, not against a re-serialised object — key order and whitespace are not guaranteed to survive a parse. Reject a `t` more than 300 seconds from your own clock, and compare the hex in constant time.


    Delivery is **at-least-once**: six attempts on an exponential backoff, a redirect is refused rather than followed, and only a 2xx within 10 seconds counts as delivered. Dedupe on `Gogoscreen-Event-Id`, and treat a repeat as the same event. After 20 consecutive failed deliveries an endpoint is disabled and has to be turned back on.


    The webhooks guide at https://gogoscreen.com/docs/webhooks has a short verifier example.'
  license:
    name: GogoScreen API Terms
    url: https://gogoscreen.com/terms
  summary: Make product walkthroughs and marketing videos from a URL.
  title: GogoScreen Voices API
  version: 1.0.0
servers:
- url: https://api.gogoscreen.com/api/v1
tags:
- description: Hearing a narration voice before spending seconds on one.
  name: Voices
paths:
  /voices/preview:
    post:
      description: 'Synthesise a short sentence in one of the catalogue''s voices and answer a short-lived link to the audio. Send your own `text` (up to 300 characters) or omit it for a stock sentence. The same sentence in the same voice is only ever synthesised once, so repeating a preview is free and instant. When somebody else is synthesising this exact preview at this moment the answer is `status: "preview_pending"` with no URL — ask again in a second.'
      operationId: voices.preview
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                text:
                  description: The sentence to speak. Omit for a stock one.
                  maxLength: 300
                  type: string
                voiceId:
                  description: A voice id from catalog.voices.list.
                  maxLength: 64
                  minLength: 1
                  type: string
              required:
              - voiceId
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  cached:
                    description: True when the audio already existed and nothing was synthesised.
                    type: boolean
                  expiresAt:
                    anyOf:
                    - format: date-time
                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                      type: string
                    - type: 'null'
                  status:
                    enum:
                    - ready
                    - preview_pending
                    type: string
                  url:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: A signed link to the audio. Null while the preview is still being made.
                required:
                - status
                - url
                - expiresAt
                - cached
                type: object
          description: Hear a voice
          headers:
            Cache-Control:
              description: Always `private, no-store`.
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`validation_failed` — That request is not valid. · `voice_unknown` — No such voice. The catalogue is at GET /api/v1/catalog/voices.'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`unauthorized` — Authentication is required.'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`forbidden_scope` — This credential does not carry the scope this operation needs.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`not_found` — No such resource.'
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`payload_too_large` — That request body is too large.'
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`unsupported_media_type` — That content type is not supported.'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`rate_limited` — Too many requests. Try again shortly.'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`internal_error` — Something went wrong. Try again.'
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`preview_failed` — That preview could not be made. Try again shortly.'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`storage_unavailable` — File storage is temporarily unavailable. · `tts_unavailable` — Voice previews are temporarily unavailable.'
      security:
      - ApiKey:
        - catalog:read
      - DashboardSession: []
      summary: Hear a voice
      tags:
      - Voices
      x-actors:
      - user
      - api_key
      x-async-kind: null
      x-audit: null
      x-idempotent: false
      x-kind: read
      x-mcp-tool: voices_preview
      x-rate-class: expensive
      x-rate-per-minute: 20
      x-scopes:
      - catalog:read
components:
  schemas:
    Error:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              description: The machine-readable refusal. Branch on this.
              enum:
              - abuse_check_unavailable
              - account_blocked
              - account_deleted
              - account_pending_deletion
              - ai_rate_limited
              - already_settled
              - anon_lifetime_cap
              - assistant_conversation_full
              - assistant_daily_limit
              - assistant_unavailable
              - avatar_unavailable
              - avatar_unknown
              - background_unknown
              - body_invalid
              - brand_kit_required
              - brand_logo_not_retained
              - brand_logo_source_mismatch
              - budget_exhausted
              - campaign_copy_overflow
              - campaign_logo_aspect_unsupported
              - campaign_speed_breaks_music_ending
              - campaign_speed_breaks_narration_fit
              - campaign_speed_not_offered
              - campaign_unsupported_claim
              - campaign_visuals_insufficient
              - caption_style_unknown
              - capture_incompatible
              - capture_unknown
              - conflict
              - conversation_closed
              - conversation_not_found
              - credentials_required
              - description_invalid
              - edit_not_understood
              - email_unverified
              - expected_revision_required
              - expired
              - export_in_flight
              - feature_disabled
              - forbidden_scope
              - gallery_example
              - generation_busy
              - generation_idempotency_conflict
              - generation_not_found
              - generation_not_retryable
              - gone
              - handoff_failed
              - handoff_limit
              - hint_improve_failed
              - hint_required
              - hint_too_long
              - idempotency_conflict
              - idempotency_in_progress
              - idempotency_key_required
              - idempotency_key_unscoped
              - insufficient_seconds
              - internal_error
              - invalid_brand_kit
              - invalid_campaign_narration
              - invalid_cover_text
              - invalid_cursor
              - invalid_revision
              - language_unknown
              - length_below_minimum
              - login_origins_invalid
              - login_url_invalid
              - login_url_required
              - missing_required_footage
              - name_invalid
              - no_beats
              - no_revision
              - not_finished
              - not_found
              - not_ready
              - options_invalid
              - orientation_unknown
              - origin_daily_cap
              - paid_account_required
              - payload_too_large
              - preview_failed
              - project_not_found
              - queue_unavailable
              - rate_limited
              - reservation_failed
              - revision_configuration_mismatch
              - revision_conflict
              - service_unavailable
              - settings_invalid
              - site_not_allowed
              - source_deleted
              - source_expired
              - source_export_in_flight
              - source_idempotency_conflict
              - source_inspection_busy
              - source_inspection_stopping
              - source_kind_mismatch
              - source_not_found
              - source_not_ready
              - source_owner_not_found
              - source_owner_unavailable
              - source_refresh_url_mismatch
              - source_render_not_found
              - source_unreadable
              - source_version_expired
              - source_version_mismatch
              - source_version_not_found
              - storage_unavailable
              - storyboard_empty
              - storyboard_expired
              - storyboard_in_flight
              - template_limit
              - template_not_found
              - template_unknown
              - too_many_endpoints
              - too_many_in_flight
              - tts_unavailable
              - unauthorized
              - unknown_beat
              - unknown_template
              - unsupported_audio_mode
              - unsupported_duration
              - unsupported_export
              - unsupported_format
              - unsupported_media_type
              - url_bare_host
              - url_blocked
              - url_credentials
              - url_dns
              - url_invalid
              - url_malformed
              - url_missing
              - url_no_host
              - url_private
              - url_scheme
              - validation_failed
              - vault_unavailable
              - verification_required
              - voice_language
              - voice_unknown
              - wallet_unavailable
              - webhook_endpoint_disabled
              - webhook_host_denied
              - webhook_url_blocked
              - webhook_url_invalid
              - website_demo_invalid
              type: string
            details:
              additionalProperties: true
              description: 'The structured half: the fields that failed, the seconds needed, the statuses offered. A refusal you can act on may also carry `missing`: one entry per thing to put right, each `{ field, section, message }`, where `section` is the part of the editor that owns the field (story, style, sound or export) and `message` is the sentence a person is shown for it. It is the same list the dashboard draws beside its Export button.'
              type: object
            message:
              description: A sentence written for a person. Never contains what you sent.
              type: string
            requestId:
              description: Quote this when reporting a failure.
              type:
              - string
              - 'null'
          required:
          - code
          - message
          - requestId
          type: object
      required:
      - error
      type: object
  securitySchemes:
    ApiKey:
      bearerFormat: gsk_…
      description: An API key, created in the dashboard's developer console. Also accepted as `X-API-Key`.
      scheme: bearer
      type: http
    DashboardSession:
      bearerFormat: JWT
      description: A dashboard session token, the credential the dashboard itself holds.
      scheme: bearer
      type: http
x-rate-classes:
  charge:
    perMinute: 20
  expensive:
    perMinute: 20
  read:
    perMinute: 600
  write:
    perMinute: 120
x-scopes:
- catalog:read
- account:read
- wallet:read
- usage:read
- storyboards:read
- storyboards:write
- renders:read
- renders:write
- marketing:read
- marketing:write
- marketing:export
- webhooks:manage
- keys:manage
- assistant:use