> ## 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.

# Grok Video Generation

> Use `POST /v1/videos` to invoke the Grok video series models and submit asynchronous generation tasks.

# Grok Video Generation

OpenAI-format entry point. If you need to use the unified video `POST /v1/video/create`, see [Create Video](./unified-generation).

The Grok video generation API uses `multipart/form-data` for submission. Please organize the request according to the fields here.

* The endpoint path is `POST /v1/videos`.
* `input_reference` is the reference image field and supports uploading multiple images repeatedly.
* `grok-video-3-pro` will be automatically fixed to `10` seconds, and `grok-video-3-max` will be automatically fixed to `15` seconds.
* The base version `grok-video-3` has no additional fixed-seconds logic and is processed according to the actual parameters passed.

## Currently Available Models

* `grok-video-3`
* `grok-video-3-pro`
* `grok-video-3-max`

## Method and Path

```http theme={null}
POST /v1/videos
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=grok-video-3" \
    -F "prompt=猫咪听歌摇头晃脑，下大雨" \
    -F "aspect_ratio=2:3" \
    -F "seconds=6" \
    -F "size=720P" \
    -F "input_reference=@reference.png"
  ```

  ```python theme={null}
  import requests

  with open("reference.png", "rb") as f:
      resp = requests.post(
          "https://octopusx.ai/v1/videos",
          headers={"Authorization": "Bearer YOUR_API_KEY"},
          data={
              "model": "grok-video-3",
              "prompt": "猫咪听歌摇头晃脑，下大雨",
              "aspect_ratio": "2:3",
              "seconds": 6,
              "size": "720P",
          },
          files={"input_reference": ("reference.png", f, "image/png")},
          timeout=60,
      )

  print(resp.json())
  ```

  ```javascript theme={null}
  const formData = new FormData();
  formData.append("model", "grok-video-3");
  formData.append("prompt", "猫咪听歌摇头晃脑，下大雨");
  formData.append("aspect_ratio", "2:3");
  formData.append("seconds", "6");
  formData.append("size", "720P");
  formData.append("input_reference", fileInput.files[0]);

  const response = await fetch("https://octopusx.ai/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
    body: formData,
  });

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

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_abc123",
    "object": "video",
    "model": "grok-video-3",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600,
    "size": "720P"
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "prompt is required",
      "type": "new_api_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid token",
      "type": "new_api_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. The currently available Grok series values are `grok-video-3`, `grok-video-3-pro`, and `grok-video-3-max`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt.
</ParamField>

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

<ParamField body="seconds" type="integer">
  Target duration in seconds. For `grok-video-3-pro` and `grok-video-3-max`, this will be automatically corrected to a fixed value.
</ParamField>

<ParamField body="size" type="string">
  Resolution tier. Common values are `720P` or `1080P`.
</ParamField>

<ParamField body="input_reference" type="file">
  Reference image file. Can be passed multiple times, corresponding to multiple `input_reference` uploads.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Task ID.
</ResponseField>

<ResponseField name="object" type="string">
  Fixed as `video`.
</ResponseField>

<ResponseField name="model" type="string">
  The actual submitted model name.
</ResponseField>

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

<ResponseField name="progress" type="integer">
  Progress percentage.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Creation timestamp.
</ResponseField>

<ResponseField name="size" type="string">
  Output resolution tier.
</ResponseField>

## Use Cases

### Text-to-Video

Just pass the fields `model`, `prompt`, `seconds`, and `size`.

### Image-to-Video

On top of text-to-video, add one or more `input_reference` files.

### Fixed-Duration Models

If you pass `grok-video-3-pro` or `grok-video-3-max`, expect the server to process them with a fixed duration.

## Related APIs

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