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

# Create Video

> Use `POST /v1/video/create` to submit Grok asynchronous generation tasks through a unified video format.

# Create Video

The Grok unified video entry point uses `POST /v1/video/create`, and the request body is JSON. Unlike [Grok video generation in OpenAI format](./generation), this endpoint uses fields such as `images`, `aspect_ratio`, and `size`, and supports referencing multiple images in `prompt` via `@img1`, `@img2`.

* The routing entry point is `POST /v1/video/create`.
* Reference images are passed through the `images` array as URLs or base64; text-to-video can pass `[]`.
* The common model is `grok-video-3`; use the model actually available on the current channel.
* After a successful submission, `id` or `task_id` and `status` are returned. Use [Query Task](./unified-query) to poll for the result later.

## Method and Path

```http theme={null}
POST /v1/video/create
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  # Text-to-video / first and last frame (images is empty or images are provided per scenario)
  curl -X POST https://octopusx.ai/v1/video/create \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "model": "grok-video-3",
      "prompt": "cat fish --mode=custom",
      "images": [],
      "aspect_ratio": "3:2",
      "size": "1080P",
      "duration": 10
    }'
  ```

  ```bash theme={null}
  # Multi-image reference (use @img1, @img2 in prompt to reference the order in images)
  curl -X POST https://octopusx.ai/v1/video/create \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "grok-video-3",
      "prompt": "@img1 a cat holding a knife chasing @img2",
      "images": [
        "data:image/png;base64,BASE64_IMAGE_1",
        "data:image/png;base64,BASE64_IMAGE_2"
      ],
      "aspect_ratio": "3:2",
      "size": "1080P",
      "duration": 6
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/video/create",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={
          "model": "grok-video-3",
          "prompt": "cat fish --mode=custom",
          "images": [],
          "aspect_ratio": "3:2",
          "size": "1080P",
          "duration": 10,
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch("https://octopusx.ai/v1/video/create", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({
      model: "grok-video-3",
      prompt: "cat fish --mode=custom",
      images: [],
      aspect_ratio: "3:2",
      size: "1080P",
      duration: 10,
    }),
  });

  console.log(await response.json());
  ```
</CodeGroup>

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "grok:48a67431-0708-46d1-9ab9-83cb84700153",
    "status": "processing",
    "status_update_time": 1762780400,
    "task_id": "48038932-0ff5-4251-8b4b-7a76c09fd114",
    "created_at": "2025-11-08T23:07:57.510141923+08:00"
  }
  ```
</ResponseExample>

The actual response fields may vary slightly by channel. Please use `id` or `task_id` in the response as the credential for subsequent queries.

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  Model name, for example `grok-video-3`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt. When using multi-image reference, you can use placeholders such as `@img1` and `@img2` in the text, corresponding to the order of indices in the `images` array.
</ParamField>

<ParamField body="images" type="array<string>" required>
  List of reference images, where each element is a URL or a base64 data URI. Text-to-video can pass `[]`; first-and-last-frame inputs are usually provided as 2 images in order; multi-image reference supports up to 6 images.
</ParamField>

<ParamField body="aspect_ratio" type="string" required>
  Video aspect ratio. Optional values are `16:9`, `9:16`, `2:3`, `3:2`, `1:1`.
</ParamField>

<ParamField body="size" type="string" required>
  Resolution specification, pass `720P` or `1080P`.
</ParamField>

<ParamField body="duration" type="integer">
  Video duration in seconds. Default is `10`; supports `6`, `10`, and `15`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Task ID, used as the `id` parameter when querying; some responses may return only `task_id`.
</ResponseField>

<ResponseField name="task_id" type="string">
  Upstream task ID, which may coexist with `id`; subject to the actual response.
</ResponseField>

<ResponseField name="status" type="string">
  Task status. Common values include `processing`, `completed`, and `failed`.
</ResponseField>

<ResponseField name="status_update_time" type="integer">
  Most recent status update time (Unix timestamp).
</ResponseField>

<ResponseField name="created_at" type="string">
  Creation time, which in some responses is an RFC3339 string.
</ResponseField>

## Related Endpoints

* [Grok Video Overview](./overview)
* [Video Remix](./unified-remix)
* [Video Extend](./unified-extend)
* [Video Extensions](./unified-extensions)
* [Query Task](./unified-query)
* [Grok Video Generation (OpenAI Format)](./generation)