> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. # Create Video Agent Session > One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes. ## OpenAPI ````yaml /openapi/external-api.json post /v3/video-agents 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: 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) paths: /v3/video-agents: post: tags: - Video Agent summary: Create Video Agent Session description: >- One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes. operationId: createVideoAgentV3 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateVideoAgentRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CreateVideoAgentResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: '''prompt'' is required and must be 1-10000 characters.' param: prompt 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 '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: CreateVideoAgentRequest: additionalProperties: false description: >- Request body for creating a video from a prompt using Video Agent v3. All configuration is flat (no nested config object). Files use the type-discriminated AssetInput union for flexible asset inputs. Supports two modes: - ``generate`` (default): one-shot — auto-proceeds through storyboard, produces one video. - ``chat``: multi-turn — may pause for user input on real decisions (e.g. pick a voice), auto-proceeds on confirmations. Allows revisions and follow-up videos. properties: prompt: description: The message/prompt for video generation (1-10000 characters) maxLength: 10000 minLength: 1 title: Prompt type: string mode: $ref: '#/components/schemas/SessionMode' default: generate description: >- Session mode. 'generate' produces one video (fire-and-forget). 'chat' enables multi-turn interaction — the agent may pause for decisions and allows revisions. avatar_id: anyOf: - type: string - type: 'null' default: null description: Specific avatar ID to use title: Avatar Id voice_id: anyOf: - type: string - type: 'null' default: null description: Specific voice ID to use for narration title: Voice Id style_id: anyOf: - type: string - type: 'null' default: null description: >- Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video. title: Style Id brand_kit_id: anyOf: - type: string - type: 'null' default: null description: >- Brand kit ID to apply brand colors, fonts, and logos to the generated video. title: Brand Kit Id orientation: anyOf: - enum: - landscape - portrait type: string - type: 'null' default: null description: Video orientation. If not provided, auto-detected from content. title: Orientation files: anyOf: - items: 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' maxItems: 20 type: array - type: 'null' default: null description: Optional file attachments (max 20 files) title: Files callback_url: anyOf: - type: string - type: 'null' default: null description: Webhook URL for completion/failure notifications title: Callback Url callback_id: anyOf: - type: string - type: 'null' default: null description: Optional callback ID included in webhook payload title: Callback Id incognito_mode: default: false description: >- When enabled, disables memory injection and extraction for this session title: Incognito Mode type: boolean required: - prompt title: CreateVideoAgentRequest type: object CreateVideoAgentResponse: description: >- Response from creating a video agent session. Designed as a session resource for future extensibility — GET /v3/video-agents/{session_id} can return the same shape enriched with more fields (messages, video URL, etc.). properties: session_id: description: Session ID — primary identifier for this video agent session examples: - sess_012abc345def678 title: Session Id type: string status: description: Session status enum: - generating - thinking - completed - failed examples: - generating title: Status type: string video_id: anyOf: - type: string - type: 'null' default: null description: >- Video ID for polling via GET /v3/videos/{video_id}. Nullable in future multi-turn flows. examples: - v_abc123def456 title: Video Id created_at: description: Unix timestamp of session creation examples: - 1711929600 title: Created At type: integer required: - session_id - status - created_at title: CreateVideoAgentResponse 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 SessionMode: enum: - generate - chat title: SessionMode type: string 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 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. ````