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

# Start Video Export

> Export a generated video to downloadable MP4 format

## Overview

This endpoint exports a completed video to a downloadable MP4 file. Use this after your video generation is complete to get the final downloadable video file.

## Authentication

<Info>
  This endpoint requires API key authentication. Export costs may apply depending on how the video was created.
</Info>

## Request Body

<ParamField body="video_id" type="string" required>
  The video ID returned from completed video generation.
</ParamField>

<ParamField body="format" type="string">
  Export format override: `vertical` (9:16), `ads` (4:5), `square` (1:1), `horizontal` (16:9), or `custom`.
  If not specified, uses the original video format.
</ParamField>

<ParamField body="width" type="number">
  Custom video width in pixels (max 5000). Only used when format is `custom`. Defaults to 1080.
</ParamField>

<ParamField body="height" type="number">
  Custom video height in pixels (max 5000). Only used when format is `custom`. Defaults to 1920.
</ParamField>

<ParamField body="avatar_model" type="string">
  Avatar model quality: `standard`, `premium`, `ultra`, `veo-3-fast`, `veo-3`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2`, `seedance-2-fast`, or `seedance-2-1080p`.
  Available models for each avatar are returned in the `model_available` field when fetching avatars from the [avatar list endpoint](/api-reference/avatar/list).
  If not specified, the system automatically selects the best default model for your avatar (standard or premium).
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive webhook notifications when export completes.
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Unique identifier for the export job.
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: `pending`.
</ResponseField>

<ResponseField name="estimated_credits" type="number">
  Estimated credit cost for this export (0 for API-generated videos).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/export/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "video_id": "vid_xyz789",
      "format": "vertical",
      "webhook_url": "https://your-app.com/webhooks/export"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/export/start"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "video_id": "vid_xyz789",
      "format": "vertical",
      "webhook_url": "https://your-app.com/webhooks/export"
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/export/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_id: "vid_xyz789",
      format: "vertical",
      webhook_url: "https://your-app.com/webhooks/export"
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "job_id": "export_abcd1234",
    "status": "pending",
    "estimated_credits": 0
  }
  ```

  ```json Error 400 - Missing Video ID theme={null}
  {
    "error": "video_id parameter is required",
    "code": "MISSING_VIDEO_ID"
  }
  ```

  ```json Error 404 - Video Not Found theme={null}
  {
    "error": "Video with specified ID doesn't exist",
    "code": "VIDEO_NOT_FOUND"
  }
  ```

  ```json Error 403 - Unauthorized Video theme={null}
  {
    "error": "Video doesn't belong to your space",
    "code": "UNAUTHORIZED_VIDEO"
  }
  ```
</ResponseExample>

## Export Formats

<CardGroup cols={2}>
  <Card title="Vertical (9:16)" icon="mobile">
    **1080x1920**
    Perfect for TikTok, Instagram Stories, YouTube Shorts
  </Card>

  <Card title="Ads (4:5)" icon="rectangle-vertical">
    **1080x1350**
    Best for Instagram ads, Facebook ads, LinkedIn ads
  </Card>

  <Card title="Square (1:1)" icon="square">
    **1080x1080**
    Ideal for Instagram posts, Facebook, LinkedIn
  </Card>

  <Card title="Horizontal (16:9)" icon="rectangle-wide">
    **1920x1080**
    Perfect for YouTube, websites, presentations
  </Card>

  <Card title="Custom" icon="sliders">
    **Custom dimensions**
    Set your own width and height (max 5000px each)
  </Card>
</CardGroup>

## Credit Costs

Export costs depend on how the video was created, resolution, and which avatar model you choose:

### Base Export Cost

* **API-generated videos**: **0 credits** for base export (included in generation)
* **Dashboard-created videos**: 5 credits per 30 seconds

### High Resolution Cost

Additional charges apply for videos with resolution exceeding 1080p (width > 1920px OR height > 1080px):

* **High resolution surcharge**: **2.5 credits per 30 seconds** of video

<Warning>
  This surcharge applies to both API-generated and dashboard-created videos when exporting at high resolutions.
</Warning>

### Avatar Model Costs

Avatar costs apply only when your video includes an avatar. Cost calculation varies by model type:

<CardGroup cols={2}>
  <Card title="Standard" icon="zap">
    **Free**

    Basic avatar quality with no additional cost.
  </Card>

  <Card title="Premium" icon="gem">
    **0.8 credits/sec**

    Highly realistic and dynamic avatars.
    Billed per second of **avatar visibility**.

    *Available from Start plan*
  </Card>

  <Card title="Ultra" icon="crown">
    **2.3 credits/sec**

    Enhanced realism with longer processing time.
    Billed per second of **avatar visibility**.

    *Enterprise plan only*
  </Card>

  <Card title="Veo 3 Fast" icon="bolt">
    **2.3 credits/sec**

    Google Veo 3 Fast model for quick generation.
    Billed per avatar segment (each segment = 8 seconds).

    *Available from Start plan*
  </Card>

  <Card title="Veo 3" icon="sparkles">
    **5 credits/sec**

    Google Veo 3 standard model for highest quality.
    Billed per avatar segment (each segment = 8 seconds).

    *Available from Start plan*
  </Card>

  <Card title="Veo 3 Lite" icon="zap">
    **0.5 credits/sec** (720p) · **0.8 credits/sec** (1080p)

    Affordable Google Veo 3 model with good quality at lower cost.
    720p for 4s/6s segments, 1080p for 8s segments.

    *Available from Start plan*
  </Card>

  <Card title="Seedance 2" icon="sparkles">
    **4 credits/sec**

    ByteDance Seedance 2 model for high-quality avatar generation.
    Billed per avatar segment (each segment = 8 seconds).

    *Available from Pro plan*
  </Card>

  <Card title="Seedance 2 Fast" icon="bolt">
    **3 credits/sec**

    ByteDance Seedance 2 Fast model for quick avatar generation.
    Billed per avatar segment (each segment = 8 seconds).

    *Available from Pro plan*
  </Card>
</CardGroup>

<Warning>
  **Billing difference:** Premium and Ultra models bill based on avatar visibility duration, while Veo, Ora and Seedance models bill based on avatar segments.
</Warning>

<Info>
  All costs are calculated separately. Total cost = Base export cost + High resolution cost + Avatar cost.
</Info>

**Example 1**: A 60-second API video with 40 seconds of avatar visibility using the Premium model:

* Base export (API video): 0 credits
* Avatar cost: 40s × 0.8 = 32 credits (avatar visibility duration)
* **Total**: 32 credits

**Example 2**: A 60-second API video with 3 avatar segments using Veo 3 Fast:

* Base export (API video): 0 credits
* Avatar cost: 3 segments × 8 seconds × 2.3 = 55.2 credits
* **Total**: 55.2 credits

**Example 3**: A 60-second API video exported at 3840x2160 (4K):

* Base export (API video): 0 credits
* High resolution cost: 2 × 2.5 = 5 credits (60s = 2 segments of 30s)
* **Total**: 5 credits

**Example 4**: A 90-second dashboard video at 4K with 60 seconds of Premium avatar:

* Base export: 3 × 5 = 15 credits (90s = 3 segments of 30s)
* High resolution cost: 3 × 2.5 = 7.5 credits
* Avatar cost: 60s × 0.8 = 48 credits (avatar visibility)
* **Total**: 70.5 credits

## Prerequisites

Before exporting a video:

1. **Video must be completed**: Check generation status is `completed`
2. **Valid video\_id**: Use the `video_id` from generation result
3. **Video ownership**: Video must belong to your space

## Next Steps

After starting an export:

1. **Monitor Progress**: Use `/export/status/{jobId}` to check export progress
2. **Download Video**: Get the download URL when export completes
3. **Webhook Integration**: Set up webhooks for automatic notifications

## Error Codes

* `MISSING_VIDEO_ID`: video\_id parameter is required
* `VIDEO_NOT_FOUND`: Video with specified ID doesn't exist
* `UNAUTHORIZED_VIDEO`: Video doesn't belong to your space
* `VIDEO_NOT_READY`: Video generation must be completed first
* `INVALID_FORMAT`: Invalid export format specified
* `INVALID_AVATAR_MODEL`: Invalid avatar model specified
* `INCOMPATIBLE_AVATAR_MODEL`: Avatar model not compatible with this avatar
* `INVALID_PARAMETER`: avatar\_model cannot be used when video has no avatar
* `INSUFFICIENT_CREDITS`: Not enough credits for export (dashboard videos only)