> ## 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. # Create HyperFrames Render > Renders a HyperFrames composition (an HTML+JS+assets project bundled as a .zip) into a video. Submit the project via `url`, `asset_id` (pre-uploaded via POST /v3/assets), or inline `base64`. Returns a `render_id` to poll via GET /v3/hyperframes/renders/{render_id}. ## OpenAPI ````yaml /openapi/external-api.json post /v3/hyperframes/renders 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 Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Avatar Realtime description: >- Low-latency streaming avatar sessions — create a stream, poll for its HLS URL, push text, consume per-word timestamps - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions paths: /v3/hyperframes/renders: post: tags: - HyperFrames summary: Create HyperFrames Render description: >- Renders a HyperFrames composition (an HTML+JS+assets project bundled as a .zip) into a video. Submit the project via `url`, `asset_id` (pre-uploaded via POST /v3/assets), or inline `base64`. Returns a `render_id` to poll via GET /v3/hyperframes/renders/{render_id}. operationId: createHyperframesRenderV3 parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHyperframesRenderRequest' responses: '202': description: Accepted — submission acknowledged; poll for completion. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateHyperframesRenderResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: Composition zip is invalid or missing index.html. param: project doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: authentication_failed message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '409': $ref: '#/components/responses/IdempotencyInProgress' '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: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 `request_in_progress`. Keys must be 1–255 characters from `[A-Za-z0-9_:.-]`; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. schema: type: string pattern: ^[A-Za-z0-9_\-:.]{1,255}$ maxLength: 255 minLength: 1 example: 550e8400-e29b-41d4-a716-446655440000 schemas: CreateHyperframesRenderRequest: additionalProperties: false description: Request body for POST /v3/hyperframes/renders. properties: project: description: >- HyperFrames composition .zip — provide as {type: 'url', url: '...'}, {type: 'asset_id', asset_id: '...'} (pre-uploaded via POST /v3/assets), or {type: 'base64', media_type: 'application/zip', data: '...'}. Zip must contain index.html at the root (or the path you set in `composition`). discriminator: mapping: asset_id: $ref: '#/components/schemas/AssetId' base64: $ref: '#/components/schemas/AssetBase64' url: $ref: '#/components/schemas/AssetUrl' propertyName: type oneOf: - $ref: '#/components/schemas/AssetUrl' - $ref: '#/components/schemas/AssetId' - $ref: '#/components/schemas/AssetBase64' title: Project fps: anyOf: - maximum: 240 minimum: 1 type: integer - type: 'null' default: 30 description: Output frames per second. Defaults to 30 if not provided. title: Fps quality: default: standard description: Render quality preset; higher quality is slower. enum: - draft - standard - high title: Quality type: string format: default: mp4 description: Output container/codec. enum: - mp4 - webm - mov title: Format type: string resolution: $ref: '#/components/schemas/HyperframesResolution' default: 1080p description: >- Output resolution tier. Defaults to '1080p'. Pass '4k' for 4K renders (billed at 1.5x). aspect_ratio: $ref: '#/components/schemas/HyperframesAspectRatio' default: '16:9' description: >- Output aspect ratio. Defaults to '16:9' (landscape). Pass '9:16' for portrait or '1:1' for square. composition: anyOf: - maxLength: 512 type: string - type: 'null' default: null description: >- Entry HTML file relative to the project root (e.g. compositions/intro.html). Defaults to index.html when omitted. title: Composition variables: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: >- Optional overrides for the composition's data-composition-variables. Use this to parameterise a single composition across multiple renders. title: Variables title: anyOf: - maxLength: 500 type: string - type: 'null' default: null description: Free-text label for the render; echoed back in detail responses. title: Title callback_id: anyOf: - maxLength: 256 type: string - type: 'null' default: null description: Opaque client tracking ID, echoed back in webhook payloads. title: Callback Id callback_url: anyOf: - type: string - type: 'null' default: null description: Per-request HTTPS webhook URL the render fires when it terminates. title: Callback Url required: - project title: CreateHyperframesRenderRequest type: object CreateHyperframesRenderResponse: description: Response for POST /v3/hyperframes/renders. properties: render_id: description: >- HyperFrames render identifier — poll GET /v3/hyperframes/renders/{render_id} for status. title: Render Id type: string required: - render_id title: CreateHyperframesRenderResponse 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 required: - code - message AssetId: additionalProperties: false description: Asset input via HeyGen asset ID from the asset upload endpoint. properties: type: const: asset_id description: Input type discriminator title: Type type: string asset_id: description: HeyGen asset ID from the asset upload endpoint title: Asset Id type: string required: - type - asset_id title: AssetId type: object AssetBase64: additionalProperties: false description: Asset input via base64-encoded content. properties: type: const: base64 description: Input type discriminator title: Type type: string media_type: description: MIME type of the encoded content (e.g. "image/png") title: Media Type type: string data: description: Base64-encoded file content title: Data type: string required: - type - media_type - data title: AssetBase64 type: object x-mcp-visible: false AssetUrl: additionalProperties: false description: Asset input via publicly accessible HTTPS URL. properties: type: const: url description: Input type discriminator title: Type type: string url: description: Publicly accessible HTTPS URL for the asset title: Url type: string required: - type - url title: AssetUrl type: object HyperframesResolution: description: |- Output resolution tier. Pricing diverges only at 4K (1.5x multiplier). The render-pipeline value set is intentionally narrow at launch; 720p and other tiers will follow once the producer/CLI surface catches up. enum: - 1080p - 4k title: HyperframesResolution type: string HyperframesAspectRatio: description: >- Output aspect ratio. Only the three ratios already supported end-to-end by the render pipeline are exposed today: ``16:9`` (landscape), ``9:16`` (portrait), ``1:1`` (square). ``auto`` and other social-media ratios (4:5, 5:4) are reserved for a follow-up PR that wires composition-dim inference at the controller boundary. enum: - '16:9' - '9:16' - '1:1' title: HyperframesAspectRatio type: string responses: IdempotencyInProgress: description: >- A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null 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. ````