> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get HyperFrames Render

> Returns full details for a single HyperFrames render, including status and signed video_url when complete.



## OpenAPI

````yaml /openapi/external-api.json get /v3/hyperframes/renders/{render_id}
openapi: 3.1.0
info:
  title: HeyGen External API
  version: 1.0.0
  description: >-
    HeyGen's external API for programmatic AI video creation. See
    https://docs.heygen.com for full documentation.
  contact:
    name: HeyGen Product Infra
    url: https://heygen.com
servers:
  - url: https://api.heygen.com
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Video
    description: >-
      Create videos from a prompt or an avatar, then list, fetch, deliver and
      delete them
  - name: Avatar
    description: >-
      Create avatars and looks, record consent, and generate with the Avatar 6
      model
  - name: Voice
    description: Text to speech, speech to speech, and voice cloning
  - name: Audio
    description: Music, sound effects, transcription, stem separation and audio analysis
  - name: Image
    description: Generate images
  - name: Video editing
    description: >-
      Translate, lipsync, clip, analyze and remove filler words or backgrounds
      from existing videos
  - name: Video Agent
    description: Create videos from a prompt with an agent that plans, writes and edits
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: HyperFrames
    description: Render HyperFrames compositions into video
  - name: Brand
    description: >-
      Brand kits (colors, fonts, logos) and brand glossaries (term translations
      and pronunciations)
  - name: Assets and folders
    description: Upload files and organize them in folders
  - name: Batches
    description: Submit and track videos, translations, lipsyncs and uploads in bulk
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Feedback
    description: Tell HeyGen how a generated result turned out
  - name: Account and usage
    description: Your account, the current API key, request logs and usage
paths:
  /v3/hyperframes/renders/{render_id}:
    get:
      tags:
        - HyperFrames
      summary: Get HyperFrames Render
      description: >-
        Returns full details for a single HyperFrames render, including status
        and signed video_url when complete.
      operationId: getHyperframesRenderV3
      parameters:
        - name: render_id
          in: path
          required: true
          schema:
            type: string
          description: Unique HyperFrames render identifier
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/HyperframesRenderDetail'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired API key. Verify your x-api-key header.
                  param: null
                  doc_url: null
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: not_found
                  message: HyperFrames render not found.
                  param: null
                  doc_url: null
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Retry after the duration specified in the
                    Retry-After header.
                  param: null
                  doc_url: null
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    HyperframesRenderDetail:
      description: Detailed HyperFrames render resource.
      properties:
        render_id:
          description: Unique render identifier.
          title: Render Id
          type: string
        status:
          $ref: '#/components/schemas/HyperframesRenderStatus'
          description: Current lifecycle state.
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Caller-supplied free-text label.
          title: Title
        callback_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Caller-supplied client tracking ID.
          title: Callback Id
        video_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Presigned download URL for the rendered video. Present only when
            status is 'completed'.
          title: Video Url
        thumbnail_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Presigned download URL for the auto-generated thumbnail.
          title: Thumbnail Url
        duration:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Video duration in seconds; null until completed.
          title: Duration
        fps:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: >-
            Frames per second the render was created at, as a whole number. A
            23.976, 29.97 or 59.94 render reports 24, 30 or 60.
          title: Fps
        fps_exact:
          anyOf:
            - enum:
                - 24000/1001
                - 30000/1001
                - 60000/1001
              type: string
            - type: 'null'
          default: null
          description: >-
            The exact rate of a 23.976, 29.97 or 59.94 render: '24000/1001',
            '30000/1001' or '60000/1001'. Absent for a whole rate.
          title: Fps Exact
        quality:
          anyOf:
            - enum:
                - draft
                - standard
                - high
              type: string
            - type: 'null'
          default: null
          description: Render quality preset.
          title: Quality
        format:
          description: Output container/codec.
          enum:
            - mp4
            - webm
            - mov
          title: Format
          type: string
        resolution:
          anyOf:
            - $ref: '#/components/schemas/HyperframesResolution'
            - type: 'null'
          default: null
          description: Resolution tier, if one was set.
        aspect_ratio:
          anyOf:
            - $ref: '#/components/schemas/HyperframesAspectRatio'
            - type: 'null'
          default: null
          description: Aspect ratio, if one was set.
        composition:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Composition entry file path.
          title: Composition
        reference_background:
          anyOf:
            - $ref: '#/components/schemas/HyperframesReferenceBackground'
            - type: 'null'
          default: null
          description: >-
            The renderer's computed background of the composition root at its
            first frame: kind 'solid' with an opaque `rgb` ([r, g, b], 0-255),
            'none' when the composition declares no background paint,
            'unsupported_non_solid' for a gradient or image, or 'unknown' when
            the renderer could not establish one. Absent for renders that did
            not report it.
        created_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Unix timestamp when the render was created.
          title: Created At
        completed_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: >-
            Unix timestamp when the render terminated. Null until status is
            'completed' or 'failed'.
          title: Completed At
        failure_message:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Error description. Present only when status is 'failed'.
          title: Failure Message
        failure_code:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Why billing refused a finished render: 'hf_usage_exhausted',
            'hf_subscription_required' or 'api_key_required', for which nothing
            was charged and the render can be sent again on a HeyGen API key; or
            'usage_limit_reached', when a usage limit a workspace admin set (the
            API key's credit limit or the member's usage limit) was reached;
            sending the render again does not help until the limit is raised or
            resets, and `failure_message` is the limit's own message; or
            'chunk_frames_exceed_timeout_at_max_chunks', when the render is too
            long to export at its size (even split into the most cloud parts
            allowed, it would still take longer than the time limit): sending it
            again fails the same way until it is shortened or rendered at a
            lower resolution or frame rate, and `failure_message` says so; or
            'output_resolution_unfit', when the composition's size cannot render
            at the requested resolution (it is not a whole-number multiple of a
            frame of that resolution in its shape): sending it again fails the
            same way until the composition is resized or rendered at 1080p, and
            `failure_message` says why; or 'PLAN_TOO_LARGE', when the render's
            working files exceed the size limit: shorten the composition, lower
            the frame rate or split the render into smaller segments, and
            `failure_message` gives the sizes; or 'VARIABLES_INVALID', when
            `strict_variables` was set and a variable does not match the
            composition's declarations: fix the variable or its declaration, and
            `failure_message` names it. Every other failure carries a code too,
            so a client can tell them apart when `failure_message` is the
            generic line: the renderer's own `<phase>:<kind>` (for example
            'capture:sub_timeline_script_failure', a script in the composition
            threw before its timeline registered), a bare phase, a classified
            code such as 'FONT_FETCH_FAILED', or 'render_failed' when nothing
            more was recorded. Present whenever status is 'failed'.
          title: Failure Code
        failure_detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            At most 300 characters, only when status is 'failed' and the failure
            is an error the composition's own script raised (the text the
            HyperFrames CLI prints for it locally, such as 'TypeError: ...
            [thrown at: hyperframes-composition://body:1:17]'). Never a file
            path, host or stack frame of ours; when the text cannot be told
            apart from those, it is null and `failure_code` is the whole answer.
          title: Failure Detail
      required:
        - render_id
        - status
        - format
      title: HyperframesRenderDetail
      type: object
    StandardAPIError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: invalid_parameter
        message:
          type: string
          description: Human-readable error message
          example: Video not found
        param:
          type:
            - string
            - 'null'
          description: Which request field caused the error
        doc_url:
          type:
            - string
            - 'null'
          description: Link to error documentation
        errors:
          type: array
          description: >-
            Per-item error details for batch/multi-node failures (e.g. graph
            compilation errors by node).
          items:
            $ref: '#/components/schemas/StandardAPIErrorDetail'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      required:
        - code
        - message
    HyperframesRenderStatus:
      description: Lifecycle status of a HyperFrames render.
      enum:
        - queued
        - rendering
        - completed
        - failed
      title: HyperframesRenderStatus
      type: string
    HyperframesResolution:
      description: Output resolution tier.
      enum:
        - 1080p
        - 4k
      title: HyperframesResolution
      type: string
    HyperframesAspectRatio:
      description: |-
        Output aspect ratio.

        Supported ratios are ``16:9`` (landscape), ``9:16`` (portrait), ``1:1``
        (square), and ``4:5`` (portrait feed post, 1080p only).
      enum:
        - '16:9'
        - '9:16'
        - '1:1'
        - '4:5'
      title: HyperframesAspectRatio
      type: string
    HyperframesReferenceBackground:
      additionalProperties: false
      description: >-
        The renderer's computed background of the composition root; `rgb` is
        present only for kind `solid`.
      properties:
        kind:
          enum:
            - solid
            - none
            - unsupported_non_solid
            - unknown
          title: Kind
          type: string
        rgb:
          anyOf:
            - maxItems: 3
              minItems: 3
              prefixItems:
                - maximum: 255
                  minimum: 0
                  type: integer
                - maximum: 255
                  minimum: 0
                  type: integer
                - maximum: 255
                  minimum: 0
                  type: integer
              type: array
            - type: 'null'
          default: null
          title: Rgb
      required:
        - kind
      title: HyperframesReferenceBackground
      type: object
    StandardAPIErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: unknown_node_type
        message:
          type: string
          description: Human-readable error message
          example: Unknown node type
        node_id:
          type: string
          description: Graph node id this error pertains to, if applicable
        port:
          type: string
          description: Port name on the node this error pertains to, if applicable
        path:
          type: string
          description: Field path within the item this error pertains to, if applicable
      required:
        - code
        - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: HeyGen API key. Obtain from your HeyGen dashboard.
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.