Name: HeyGen Video Agent Prompt-to-Video API
Brand: magicapi
SKU: api-magicapi-text-to-video-generator-heygen-video-agent
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 AI Video Agent API - Prompt to Finished Presenter Video (HeyGen Video Agent)

## Overview
Video Agent is HeyGen's prompt-to-video agent. Its developer describes it as turning a text prompt into a complete, polished video with an AI-generated script, avatar presenter, voiceover, visuals and editing.

Send a `prompt` that describes the video you want. Optionally set an approximate length with `duration_sec` (5 seconds or more) and an `orientation` (`landscape` or `portrait`). The agent picks the avatar and voice itself unless you pass a HeyGen `avatar_id` or `voice_id`, and `style_id` selects one of HeyGen's visual style templates. Each request returns the URL of one MP4 video.

`avatar_id`, `voice_id` and `style_id` take HeyGen ids. These ids come from HeyGen's own catalog and are not listed on api.market; leave them empty to let the agent choose.

## Features
- **Prompt to finished video**: the agent handles avatar selection, scripting, scenes and editing from one `prompt`.
- **Target length**: `duration_sec` sets an approximate target duration in seconds (minimum 5). The final video can be shorter or longer.
- **Orientation**: `landscape` or `portrait`; leave `orientation` empty to let the agent decide.
- **Optional presenter and voice**: pass a HeyGen `avatar_id` or `voice_id`, or leave them empty and the agent selects them.
- **Style templates**: `style_id` selects a HeyGen visual style template that controls scene composition, pacing and aesthetics.

## Use Cases
1. **Product explainers**: describe a product or feature and get a presenter-led explainer video.
2. **Announcements**: turn a release note or event description into a short video for social media or a newsletter.
3. **Course and training intros**: describe a lesson and let the agent script and present it.
4. **Vertical social videos**: set `orientation` to `portrait` for short-form video feeds.

## Visual Examples
### Example Input
- **prompt**: "Create a short, upbeat explainer for developers introducing api.market, a marketplace where one API key unlocks hundreds of AI models for images, video and speech. End with a friendly invitation to try a model for free."
- **duration_sec**: `10`
- **orientation**: `landscape`

`avatar_id`, `voice_id` and `style_id` were left empty, so the agent chose the presenter, the voice and the look.

### Example Output
[Watch the example output](https://blog.api.market/wp-content/uploads/2026/10/video-agent-output-api-market.mp4)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  |  | Text prompt describing the video you want to create. The agent handles avatar selection, scripting, scenes and editing. |
| `avatar_id` | string | No | `""` |  | HeyGen avatar id to use. If not provided, the agent selects an appropriate avatar. Avatar ids come from HeyGen's catalog, which is not listed on api.market. |
| `voice_id` | string | No | `""` |  | HeyGen voice id for the narration. If not provided, the agent selects a voice automatically. Voice ids come from HeyGen's catalog, which is not listed on api.market. |
| `style_id` | string | No | `""` |  | Visual style template id from HeyGen's curated styles. Controls scene composition, pacing and aesthetics. Style ids come from HeyGen's catalog, which is not listed on api.market. |
| `duration_sec` | integer | No | none | 5 or more | Approximate target duration of the video in seconds. Minimum is 5. Leave empty to let the agent choose the length. |
| `orientation` | string | No | `""` | `landscape`, `portrait` or empty | Video orientation. Must be `landscape` or `portrait`. Leave empty to let the agent decide. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.042 per API unit.
- **1 API unit = 1 second of output video, rounded up per request.** You are billed on the length of the output video. `duration_sec` is only an approximate target and has no maximum, so the returned video, and the charge, can be shorter or longer than the target.
- **Worked examples**: a 10 second video is 10 units = $0.42; a 30 second video is 30 units = $1.26; a 60 second video is 60 units = $2.52.
- Orientation, avatar, voice and style do not change the per-second price.
- **The example request above** asked for about 10 seconds and returned an 11.64 second video, billed as 12 units = $0.504. The target is approximate; the charge follows the length of the returned video.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/text-to-video-generator-heygen-video-agent`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

The agent writes, renders and edits a whole video, which takes longer than an image. A polling interval of 5 seconds and an overall timeout of 1800 seconds (30 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-video-generator-heygen-video-agent/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "6f1a78bb1918384ec9776a1adc7de0f300ff2643f914aebcecce64303b1dd16f",
    "input": {
      "prompt": "Create a short, upbeat explainer for developers introducing api.market, a marketplace where one API key unlocks hundreds of AI models for images, video and speech. End with a friendly invitation to try a model for free.",
      "duration_sec": 10,
      "orientation": "landscape"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "gej430dgjdrmy0d17g3bv0rshr",
  "version": "6f1a78bb1918384ec9776a1adc7de0f300ff2643f914aebcecce64303b1dd16f",
  "status": "starting",
  "created_at": "2026-10-14T20:07:13.928Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-video-generator-heygen-video-agent/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "gej430dgjdrmy0d17g3bv0rshr",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/video-agent-output-api-market.mp4",
  "error": null,
  "created_at": "2026-10-14T20:07:13.928Z",
  "started_at": "2026-10-14T20:07:14.928Z",
  "completed_at": "2026-10-14T20:12:13.928Z"
}
```

`output` is a single URL string pointing to the generated MP4 video.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt` or a `duration_sec` below 5.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-video-generator-heygen-video-agent";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "6f1a78bb1918384ec9776a1adc7de0f300ff2643f914aebcecce64303b1dd16f", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 1800000;
  const pollInterval = 5000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 30 minutes");
}

createAndWaitForPrediction({
  "prompt": "Create a short, upbeat explainer for developers introducing api.market, a marketplace where one API key unlocks hundreds of AI models for images, video and speech. End with a friendly invitation to try a model for free.",
  "duration_sec": 10,
  "orientation": "landscape"
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-video-generator-heygen-video-agent"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "6f1a78bb1918384ec9776a1adc7de0f300ff2643f914aebcecce64303b1dd16f", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 1800
    poll_interval = 5
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 30 minutes")

print(create_and_wait_for_prediction({
  "prompt": "Create a short, upbeat explainer for developers introducing api.market, a marketplace where one API key unlocks hundreds of AI models for images, video and speech. End with a friendly invitation to try a model for free.",
  "duration_sec": 10,
  "orientation": "landscape"
}))
```

## FAQ
- **Will my video be exactly `duration_sec` long?**
  - Not necessarily. `duration_sec` is an approximate target. You are billed $0.042 per second of the video that is returned, rounded up per request.
- **Do I have to pick an avatar and a voice?**
  - No. Leave `avatar_id` and `voice_id` empty and the agent selects them. If you want a specific one, pass a HeyGen id; these ids come from HeyGen's catalog, which is not listed on api.market.
- **Can I make a vertical video?**
  - Yes. Set `orientation` to `portrait`. Leave it empty to let the agent decide.
- **How should I write the prompt?**
  - Describe the topic, the audience, the tone and how the video should end, as in the example. The agent writes the script and builds the scenes from it.
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Turn a text prompt into a finished presenter video with HeyGen Video Agent: script, avatar, voiceover, visuals and editing in one call. $0.042 per second.