> ## 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. # Send Video Agent Message > Sends a follow-up turn to a session created in either `generate` or `chat` mode; follow-up turns preserve the session mode. Send a `message`, a scene `edit_plan` built from GET /v3/videos/{video_id}/scenes, or both. Items may reference different scene snapshots from this session; none identifies the output draft. `edit_version` is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in `video_id`. Poll GET /v3/videos/{video_id} for status. For a failed video, inspect `failure_code` and `failure_message`; the session endpoint also exposes known stop reasons in `error`. ## OpenAPI ````yaml /openapi/external-api.json post /v3/video-agents/{session_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 Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - 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: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Folders description: >- Create folders to organize videos and translations in the workspace, and look up any folder, Assets library folders included, by id - 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: Models description: '' - name: Filler Word Removal description: '' paths: /v3/video-agents/{session_id}: post: tags: - Video Agent summary: Send Video Agent Message description: >- Sends a follow-up turn to a session created in either `generate` or `chat` mode; follow-up turns preserve the session mode. Send a `message`, a scene `edit_plan` built from GET /v3/videos/{video_id}/scenes, or both. Items may reference different scene snapshots from this session; none identifies the output draft. `edit_version` is not a document lock, so two edits from one version may both be accepted. Returns the current working draft in `video_id`. Poll GET /v3/videos/{video_id} for status. For a failed video, inspect `failure_code` and `failure_message`; the session endpoint also exposes known stop reasons in `error`. operationId: sendVideoAgentMessage parameters: - name: session_id in: path required: true schema: type: string description: Session ID - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessageRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SendMessageResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: missing_turn_content: summary: No message or edit plan value: error: code: invalid_parameter message: Provide a message or edit_plan. param: message doc_url: null invalid_scene: summary: Scene is not in the snapshot value: error: code: invalid_parameter message: >- Scene scene_example is not present in the current video draft. param: edit_plan doc_url: null '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: Session or scene snapshot video not found. param: null doc_url: null '409': description: >- Conflict — `error.code` is one of: `stale_edit_version`, `resource_not_ready`, `request_in_progress`, `context_limit_exceeded`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: stale_edit_version: summary: The scene graph changed value: error: code: stale_edit_version message: >- The video changed after its scenes were read. Fetch the scenes again and retry with the new edit_version. param: null doc_url: null resource_not_ready: summary: The editable draft resource is still being prepared value: error: code: resource_not_ready message: The editable Video Agent resource is not ready yet. param: null doc_url: null request_in_progress: summary: Concurrent retry with same Idempotency-Key value: error: code: request_in_progress message: >- A request with this Idempotency-Key is already in progress. Retry shortly. param: null doc_url: null context_limit_exceeded: summary: The conversation is too long to continue value: error: code: context_limit_exceeded message: >- This session's conversation has grown too long for the agent to continue. Start a new session to keep working. 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: 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: SendMessageRequest: additionalProperties: false anyOf: - properties: message: minLength: 1 type: string required: - message - properties: edit_plan: minItems: 1 type: array required: - edit_plan description: >- One conversational or scene-edit turn in an existing Video Agent session. properties: message: default: '' description: >- Text message to the agent. Required when edit_plan is omitted; may be omitted or empty when edit_plan is provided. maxLength: 10000 title: Message type: string avatar_id: anyOf: - type: string - type: 'null' default: null description: Override avatar for this message title: Avatar Id voice_id: anyOf: - type: string - type: 'null' default: null description: Override voice for this message title: Voice Id brand_kit_id: anyOf: - type: string - type: 'null' default: null description: >- Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted. title: Brand Kit Id files: anyOf: - items: discriminator: mapping: asset_id: '#/components/schemas/AssetId' base64: '#/components/schemas/AssetBase64' url: '#/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 edit_plan: anyOf: - items: $ref: '#/components/schemas/VideoAgentSceneEdit' maxItems: 50 minItems: 1 type: array - type: 'null' default: null description: >- Scene-scoped natural-language edits to validate and submit atomically. Required when message is omitted or empty. title: Edit Plan title: SendMessageRequest type: object SendMessageResponse: description: Response from submitting a turn to a session. properties: session_id: description: Session ID title: Session Id type: string run_id: description: Run ID for this message processing title: Run Id type: string title: anyOf: - type: string - type: 'null' default: null description: LLM-generated session title title: Title video_id: anyOf: - type: string - type: 'null' default: null description: >- Current working draft video ID for an edit turn; poll GET /v3/videos/{video_id} for status title: Video Id required: - session_id - run_id title: SendMessageResponse 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 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 VideoAgentSceneEdit: additionalProperties: false description: >- A public scene edit tied to the editor snapshot that supplied its scene ID. properties: scene_id: description: Scene ID returned by GET /v3/videos/{scene_snapshot_video_id}/scenes maxLength: 255 minLength: 1 title: Scene Id type: string text: description: Natural-language change to apply to this scene maxLength: 10000 minLength: 1 title: Text type: string scene_snapshot_video_id: description: >- Video ID whose GET /v3/videos/{video_id}/scenes response supplied this scene ID minLength: 1 title: Scene Snapshot Video Id type: string edit_version: description: Opaque edit version returned with that video snapshot maxLength: 64 minLength: 64 pattern: ^[0-9a-f]{64}$ title: Edit Version type: string required: - scene_id - text - scene_snapshot_video_id - edit_version title: VideoAgentSceneEdit 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.