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

# Send Feedback

> Sends feedback on one result: a video, a translation, an image, a Video Agent session, or any call by its X-Request-Id. Send a `rating`, a `comment`, or both, and set `submitted_by` to 'end_user' when you are passing on what one of your own users said. HeyGen reads this feedback to find and fix quality problems; it does not change the result, refund it, or open a support ticket. Send an Idempotency-Key to make retries safe.



## OpenAPI

````yaml /openapi/external-api.json post /v3/feedback
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/feedback:
    post:
      tags:
        - Feedback
      summary: Send Feedback
      description: >-
        Sends feedback on one result: a video, a translation, an image, a Video
        Agent session, or any call by its X-Request-Id. Send a `rating`, a
        `comment`, or both, and set `submitted_by` to 'end_user' when you are
        passing on what one of your own users said. HeyGen reads this feedback
        to find and fix quality problems; it does not change the result, refund
        it, or open a support ticket. Send an Idempotency-Key to make retries
        safe.
      operationId: createFeedbackV3
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFeedbackV3Request'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/FeedbackV3'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: invalid_parameter
                  message: send a rating, a comment, or both
                  param: null
                  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
        '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:
    CreateFeedbackV3Request:
      additionalProperties: false
      description: Request body for POST /v3/feedback.
      properties:
        resource_type:
          $ref: '#/components/schemas/FeedbackResourceTypeV3'
          description: >-
            What the feedback is about. Use the name of the resource whose ID
            you send in resource_id: 'video' for an ID from POST /v3/videos,
            'video_translation' for POST /v3/video-translations,
            'video_agent_session' for POST /v3/video-agents, 'model_video' for
            POST /v3/models/videos, 'model_image_generation' for POST
            /v3/models/images, 'image_generation' for POST /v3/images, and so
            on. For a call that returns no resource ID, such as speech
            generation, use 'request' with the response's X-Request-Id.
          examples:
            - video
        resource_id:
          description: ID of the resource the feedback is about, as the API returned it.
          examples:
            - 8d3c2f0a1b4e4c6d9e7f0a1b2c3d4e5f
          maxLength: 128
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
          title: Resource Id
          type: string
        rating:
          anyOf:
            - $ref: '#/components/schemas/FeedbackRatingV3'
            - type: 'null'
          default: null
          description: Overall verdict on the result. Send a rating, a comment, or both.
          examples:
            - negative
        comment:
          anyOf:
            - maxLength: 2000
              type: string
            - type: 'null'
          default: null
          description: >-
            What worked or what went wrong, in plain words, up to 2000
            characters. Be specific: name the moment, the element or the
            setting. Do not include personal data.
          examples:
            - >-
              The lips drift out of sync after 0:12, and the second scene's
              background flickers.
          title: Comment
        tags:
          anyOf:
            - items:
                type: string
              maxItems: 10
              type: array
            - type: 'null'
          default: null
          description: >-
            Up to 10 short reason keys in snake_case, each up to 64 characters,
            for grouping feedback. Any key is accepted; reuse the same keys
            across requests.
          examples:
            - - lip_sync
              - background
          title: Tags
        submitted_by:
          $ref: '#/components/schemas/FeedbackSubmittedByV3'
          default: agent
          description: >-
            Who the feedback comes from. 'agent' (the default) when your code or
            an AI agent judged the result; 'end_user' when you are passing on
            what one of your own users said.
      required:
        - resource_type
        - resource_id
      title: CreateFeedbackV3Request
      type: object
    FeedbackV3:
      description: One piece of feedback, as stored.
      properties:
        id:
          description: Feedback ID.
          examples:
            - 4f0e1d2c3b4a49588776655443322110
          title: Id
          type: string
        resource_type:
          $ref: '#/components/schemas/FeedbackResourceTypeV3'
          description: What the feedback is about.
          examples:
            - video
        resource_id:
          description: ID of the resource the feedback is about.
          examples:
            - 8d3c2f0a1b4e4c6d9e7f0a1b2c3d4e5f
          title: Resource Id
          type: string
        rating:
          anyOf:
            - $ref: '#/components/schemas/FeedbackRatingV3'
            - type: 'null'
          default: null
          description: Overall verdict, when one was sent.
          examples:
            - negative
        comment:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The comment, when one was sent.
          examples:
            - >-
              The lips drift out of sync after 0:12, and the second scene's
              background flickers.
          title: Comment
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: Reason keys, when any were sent.
          examples:
            - - lip_sync
              - background
          title: Tags
        submitted_by:
          $ref: '#/components/schemas/FeedbackSubmittedByV3'
          description: Who the feedback comes from.
          examples:
            - agent
        created_at:
          description: Unix timestamp (seconds) when the feedback was received.
          examples:
            - 1794850000
          title: Created At
          type: integer
      required:
        - id
        - resource_type
        - resource_id
        - submitted_by
        - created_at
      title: FeedbackV3
      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
    FeedbackResourceTypeV3:
      description: >-
        What the feedback is about. Each value names the API resource whose id
        goes in resource_id.
      enum:
        - video
        - video_translation
        - video_agent_session
        - video_generation
        - model_video
        - image_generation
        - model_image_generation
        - lipsync
        - podcast
        - voice
        - avatar_group
        - avatar_look
        - brand_kit
        - background_removal
        - filler_word_removal
        - ai_clipping
        - audio_transcription
        - music
        - stems
        - hyperframes_render
        - video_analysis
        - custom_agent_video
        - workflow_run
        - asset
        - template
        - request
      title: FeedbackResourceTypeV3
      type: string
    FeedbackRatingV3:
      enum:
        - positive
        - neutral
        - negative
      title: FeedbackRatingV3
      type: string
    FeedbackSubmittedByV3:
      enum:
        - agent
        - end_user
      title: FeedbackSubmittedByV3
      type: string
    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
  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.

````

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