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

# Create Video Quality Comparison

`POST /v3/video-quality/comparisons`

## Request

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

Submit one pairwise video comparison. The server waits for a bounded synchronous result: completed comparisons return 200, while comparisons that continue asynchronously return 202 and can be polled by comparison_id.

## Headers

- `Idempotency-Key` string

## Request body

- VideoQualityComparisonRequest: One pairwise video comparison.
  - `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 `200`

Successful response

- object
  - `data` VideoQualityComparisonResponse: A comparison resource returned by synchronous submission or polling.
    - `comparison_id` string, required: Unique comparison identifier used for polling.
    - `status` 'processing' | 'completed' | 'failed', required: Lifecycle shared by single comparisons and batches.
    - `result` VideoQualityComparisonResult: Completed pairwise judge result.
      - `model_a` string, required: Caller-supplied identifier for video A's model.
      - `model_b` string, required: Caller-supplied identifier for video B's model.
      - `winner` string, required: Winning caller-supplied model identifier.
      - `winner_side` 'a' | 'b', required: Winning candidate side: 'a' or 'b'.
      - `confidence` number, required: Winning-side probability derived from the pairwise judge.
      - `question_id` 'engagement' | 'prompt_intent' | 'composition' | 'temporal_consistency' | 'craft' | 'q1', required: Supported C2V judge questions.
      - `judge_model_version` string, required: Exact judge model version used for this comparison.
    - `error` VideoQualityComparisonError: Terminal per-comparison error returned by polling endpoints.
      - `code` string, required: Stable machine-readable failure code.
      - `message` string, required: Human-readable explanation of the comparison failure.
    - `resolved_assets` VideoQualityResolvedAssets
      - `video_a_asset_id` string, required: Owned video A asset ID, reusable as an asset_id input in later comparisons or batches.
      - `video_b_asset_id` string, required: Owned video B asset ID, reusable as an asset_id input in later comparisons or batches.

## Other responses

- `202`: Accepted — comparison continues asynchronously; poll for completion.
- `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/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)