---
title: "Create Video Quality Comparison Batch"
method: POST
path: "/v3/video-quality/comparisons/batches"
tags: ["Video Quality"]
---

# Create Video Quality Comparison Batch

`POST /v3/video-quality/comparisons/batches`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/video-quality/comparisons/batches`
- Auth: API key in header `x-api-key`

Submit up to 2000 pairwise video comparisons for asynchronous processing.

## Headers

- `Idempotency-Key` string

## Request body

- CreateVideoQualityComparisonBatchRequest: Request body for asynchronous batch submission.
  - `comparisons` VideoQualityComparisonRequest[], required: One to 2000 pairwise comparisons.
    - `prompt` string, required: Prompt used to generate both candidate videos. This provides request context, but scoring is selected by question_id and does not condition on this free-form prompt.
    - `model_a` string, required: Caller-supplied identifier for the model that generated video A.
    - `model_b` string, required: Caller-supplied identifier for the model that generated video B.
    - `video_a` union, required: Video A as a public URL, HeyGen asset ID, or base64-encoded video.
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
      - AssetBase64: Asset input via base64-encoded content.
        - `type` 'base64', required: Input type discriminator
        - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
        - `data` string, required: Base64-encoded file content
    - `video_b` union, required: Video B as a public URL, HeyGen asset ID, or base64-encoded video.
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
      - AssetBase64: Asset input via base64-encoded content.
        - `type` 'base64', required: Input type discriminator
        - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
        - `data` string, required: Base64-encoded file content
    - `question_id` 'engagement' | 'prompt_intent' | 'composition' | 'temporal_consistency' | 'craft' | 'q1', required: Supported C2V judge questions.
    - `judge_model_version` string, nullable: Allowlisted dated judge model name. Omit to use the active server-configured version.

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateVideoQualityComparisonBatchResponse: Accepted asynchronous batch.
    - `batch_id` string, required: Unique batch identifier used for polling.
    - `status` 'processing' | 'completed' | 'failed', required: Lifecycle shared by single comparisons and batches.
    - `total_items` integer, required: Number of comparisons accepted in the batch.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `409`: A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/video-quality/comparisons/batches/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)