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

# Create Video

> Generate videos from text prompts

```
POST /v1/videos
```

Creates a video generation task from a text prompt. Video generation is asynchronous - this endpoint returns a video ID that can be used to check the status and download the result.

<Info>
  Video generation can take several minutes depending on the model and parameters. Use the [Get Video](/api-reference/video/get) endpoint to check the status.
</Info>

## Request Body

This endpoint accepts `multipart/form-data`.

<ParamField body="model" type="string" required>
  The video generation model to use (e.g., `sora-2`).
</ParamField>

<ParamField body="prompt" type="string" required>
  A text description of the video to generate.
</ParamField>

<ParamField body="size" type="string">
  The dimensions of the output video (e.g., `1920x1080`, `1080x1920`, `1280x720`).
</ParamField>

<ParamField body="seconds" type="string">
  The duration of the video in seconds.
</ParamField>

<ParamField body="input_reference" type="file">
  An optional reference image or video to guide generation.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the video generation task.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the video generation. Possible values: `pending`, `processing`, `completed`, `failed`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp of when the task was created.
</ResponseField>

## Examples

### Basic Video Generation

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.voidai.app/v1/videos"
  headers = {
      "Authorization": "Bearer sk-voidai-your_key_here"
  }
  data = {
      "model": "sora-2",
      "prompt": "A serene beach at sunset with gentle waves",
      "size": "1920x1080",
      "seconds": "10"
  }

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

  print(f"Video ID: {video['id']}")
  print(f"Status: {video['status']}")
  ```

  ```typescript TypeScript theme={null}
  const formData = new FormData();
  formData.append('model', 'sora-2');
  formData.append('prompt', 'A serene beach at sunset with gentle waves');
  formData.append('size', '1920x1080');
  formData.append('seconds', '10');

  const response = await fetch('https://api.voidai.app/v1/videos', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-voidai-your_key_here'
    },
    body: formData
  });

  const video = await response.json();
  console.log(`Video ID: ${video.id}`);
  console.log(`Status: ${video.status}`);
  ```

  ```bash cURL theme={null}
  curl https://api.voidai.app/v1/videos \
    -H "Authorization: Bearer sk-voidai-your_key_here" \
    -F model="sora-2" \
    -F prompt="A serene beach at sunset with gentle waves" \
    -F size="1920x1080" \
    -F seconds="10"
  ```
</CodeGroup>

### With Reference Image

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.voidai.app/v1/videos"
  headers = {
      "Authorization": "Bearer sk-voidai-your_key_here"
  }
  data = {
      "model": "sora-2",
      "prompt": "Animate this scene with flowing water and moving clouds",
      "size": "1920x1080",
      "seconds": "5"
  }
  files = {
      "input_reference": open("reference.jpg", "rb")
  }

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

  ```bash cURL theme={null}
  curl https://api.voidai.app/v1/videos \
    -H "Authorization: Bearer sk-voidai-your_key_here" \
    -F model="sora-2" \
    -F prompt="Animate this scene with flowing water and moving clouds" \
    -F size="1920x1080" \
    -F seconds="5" \
    -F input_reference="@reference.jpg"
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "id": "vid_abc123def456",
  "status": "pending",
  "created_at": 1701691200
}
```

## Workflow

1. **Create Video** - Submit your prompt and receive a video ID
2. **Poll Status** - Use [Get Video](/api-reference/video/get) to check when processing completes
3. **Download** - Use [Download Video](/api-reference/video/download) to retrieve the final video

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

# 1. Create video
response = requests.post(
    "https://api.voidai.app/v1/videos",
    headers={"Authorization": "Bearer sk-voidai-your_key_here"},
    data={"model": "sora-2", "prompt": "A cat playing piano"}
)
video_id = response.json()["id"]

# 2. Poll for completion
while True:
    status_response = requests.get(
        f"https://api.voidai.app/v1/videos/{video_id}",
        headers={"Authorization": "Bearer sk-voidai-your_key_here"}
    )
    status = status_response.json()["status"]

    if status == "completed":
        break
    elif status == "failed":
        raise Exception("Video generation failed")

    time.sleep(10)  # Check every 10 seconds

# 3. Download video
video_response = requests.get(
    f"https://api.voidai.app/v1/videos/{video_id}/content",
    headers={"Authorization": "Bearer sk-voidai-your_key_here"}
)

with open("output.mp4", "wb") as f:
    f.write(video_response.content)
```