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

# omni-fast Video Generation

> Call `omni-fast` via `POST /v1/videos` to generate text-to-video, image-to-video, first/last frame, and multi-reference image video.

# omni-fast

`omni-fast` submits asynchronous video tasks with a JSON request body, suitable for text-to-video, first-frame image-to-video, first/last frame, and multi-reference image video.

* Asynchronous processing mode; returns `id` or `task_id` after submission.
* Text-to-video only requires `model`, `prompt`, `seconds`, and the aspect ratio field.
* First-frame image-to-video uses `first_image_url`.
* First/last frame uses `first_image_url` and `last_image_url`.
* Multi-reference images use `images`, up to 5; for reference video use `omni-fast-v2v`.

## Method and Path

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

## Request Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://www.token-nova.com/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "omni-fast",
      "prompt": "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight",
      "seconds": "8",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }'
  ```

  ```bash First Frame cURL theme={null}
  curl -X POST https://www.token-nova.com/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "omni-fast",
      "prompt": "The scene comes alive with gentle wind and drifting clouds",
      "first_image_url": "https://example.com/first-frame.jpg",
      "seconds": "8",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }'
  ```

  ```bash First/Last Frame cURL theme={null}
  curl -X POST https://www.token-nova.com/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "omni-fast",
      "prompt": "Create a smooth transition from the first frame to the last frame.",
      "first_image_url": "https://example.com/first-frame.jpg",
      "last_image_url": "https://example.com/last-frame.jpg",
      "seconds": "8",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }'
  ```

  ```bash Multi-Reference cURL theme={null}
  curl -X POST https://www.token-nova.com/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "omni-fast",
      "prompt": "Use the first image as the character reference and the second image as the visual style reference. Create a cozy cafe conversation scene.",
      "images": [
        "https://example.com/character.jpg",
        "https://example.com/style.jpg"
      ],
      "seconds": "8",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }'
  ```

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

  resp = requests.post(
      "https://www.token-nova.com/v1/videos",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "omni-fast",
          "prompt": "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight",
          "seconds": "8",
          "aspect_ratio": "16:9",
          "resolution": "720p",
      },
      timeout=120,
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://www.token-nova.com/v1/videos", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "omni-fast",
      prompt:
        "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight",
      seconds: "8",
      aspect_ratio: "16:9",
      resolution: "720p",
    }),
  });

  console.log(await response.json());
  ```

  ```go Go theme={null}
  package main

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"io"
  	"net/http"
  )

  func main() {
  	payload := map[string]any{
  		"model":        "omni-fast",
  		"prompt":       "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight",
  		"seconds":      "8",
  		"aspect_ratio": "16:9",
  		"resolution":   "720p",
  	}
  	body, _ := json.Marshal(payload)

  	req, _ := http.NewRequest("POST", "https://www.token-nova.com/v1/videos", bytes.NewReader(body))
  	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
  	req.Header.Set("Content-Type", "application/json")

  	resp, err := http.DefaultClient.Do(req)
  	if err != nil {
  		panic(err)
  	}
  	defer resp.Body.Close()

  	respBody, _ := io.ReadAll(resp.Body)
  	fmt.Println(string(respBody))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Main {
      public static void main(String[] args) throws Exception {
          String json = """
          {
            "model": "omni-fast",
            "prompt": "Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight",
            "seconds": "8",
            "aspect_ratio": "16:9",
            "resolution": "720p"
          }
          """;

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://www.token-nova.com/v1/videos"))
              .header("Authorization", "Bearer YOUR_API_KEY")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(json))
              .build();

          HttpResponse<String> response = HttpClient.newHttpClient()
              .send(request, HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php
  $payload = [
      'model' => 'omni-fast',
      'prompt' => 'Ocean waves gently rolling onto a sandy beach at golden hour, cinematic, warm sunlight',
      'seconds' => '8',
      'aspect_ratio' => '16:9',
      'resolution' => '720p',
  ];

  $ch = curl_init('https://www.token-nova.com/v1/videos');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer YOUR_API_KEY',
          'Content-Type: application/json',
      ],
      CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
      CURLOPT_RETURNTRANSFER => true,
  ]);

  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```
</RequestExample>

## Response Examples

<ResponseExample>
  ```json 200 - Submitted theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "omni-fast",
    "status": "queued",
    "progress": 0,
    "created_at": 1735689600,
    "video_url": ""
  }
  ```

  ```json 200 - Query Success theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "omni-fast",
    "status": "completed",
    "progress": 100,
    "created_at": 1735689600,
    "completed_at": 1735689900,
    "video_url": "https://example.com/results/omni-fast.mp4"
  }
  ```

  ```json 200 - Task Failed theme={null}
  {
    "id": "video_abc123",
    "task_id": "video_abc123",
    "object": "video",
    "model": "omni-fast",
    "status": "failed",
    "progress": 100,
    "error": {
      "message": "upstream task failed",
      "code": "task_failed"
    }
  }
  ```

  ```json 400 - Invalid Parameter theme={null}
  {
    "error": {
      "message": "field model is required",
      "type": "invalid_request_error",
      "param": "model",
      "code": "invalid_request_error"
    }
  }
  ```

  ```json 401 - Authentication Failed theme={null}
  {
    "error": {
      "message": "invalid token",
      "type": "invalid_request_error",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 - Insufficient Quota theme={null}
  {
    "error": {
      "message": "insufficient quota",
      "type": "insufficient_quota",
      "code": "insufficient_quota"
    }
  }
  ```

  ```json 429 - Too Many Requests theme={null}
  {
    "error": {
      "message": "rate limit exceeded",
      "type": "rate_limit_error",
      "code": "rate_limit_exceeded"
    }
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "error": {
      "message": "internal server error",
      "type": "server_error",
      "code": "server_error"
    }
  }
  ```
</ResponseExample>

## Authentication

Use Bearer Token authentication:

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

All request examples must include the `Authorization` header. JSON requests must also include:

```http theme={null}
Content-Type: application/json
```

## Body

<ParamField body="model" type="string" required>
  Fixed value `omni-fast`. Example: `"omni-fast"`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Video prompt. Example: `"Ocean waves gently rolling onto a sandy beach at golden hour"`.
</ParamField>

<ParamField body="seconds" type="string">
  Video duration. Recommended as a string; recommended range is `4` to `30` seconds. Example: `"8"`.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Aspect ratio. Example values: `"16:9"`, `"9:16"`.
</ParamField>

<ParamField body="resolution" type="string">
  Resolution field. Example values: `"720p"`, `"1080p"`, `"2k"`, `"4k"`.
</ParamField>

<ParamField body="first_image_url" type="string">
  First frame image. Passing it enters first-frame image-to-video mode. Supports public URL or `data:image/...;base64,...`. Example: `"https://example.com/first-frame.jpg"`.
</ParamField>

<ParamField body="last_image_url" type="string">
  Last frame image. Must be used together with `first_image_url`. Example: `"https://example.com/last-frame.jpg"`.
</ParamField>

<ParamField body="images" type="array<string>">
  Multi-reference image list, up to 5. Supports public URL or `data:image/...;base64,...`. Example: `["https://example.com/character.jpg"]`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Video task ID. Can be used later for `GET /v1/videos/{task_id}` queries.
</ResponseField>

<ResponseField name="task_id" type="string">
  Compatibility field for the video task ID. Usually the same as `id`.
</ResponseField>

<ResponseField name="object" type="string">
  Object type, usually `video`.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for this task, for example `omni-fast`.
</ResponseField>

<ResponseField name="status" type="string">
  Task status. Common values are `queued`, `in_progress`, `completed`, `failed`.
</ResponseField>

<ResponseField name="progress" type="number">
  Task progress, commonly in the range `0` to `100`.
</ResponseField>

<ResponseField name="video_url" type="string">
  The video URL after completion.
</ResponseField>

<ResponseField name="error" type="object">
  The error object returned when a task fails or an API error occurs, usually containing `message` and `code`.
</ResponseField>

## Use Cases

### Vertical Text-to-Video

```json theme={null}
{
  "model": "omni-fast",
  "prompt": "A woman walking through a neon-lit Tokyo street at night, rain reflections, cinematic",
  "seconds": "8",
  "aspect_ratio": "9:16",
  "resolution": "720p"
}
```

### First-Frame Image-to-Video

```json theme={null}
{
  "model": "omni-fast",
  "prompt": "The scene comes alive with gentle wind and drifting clouds",
  "first_image_url": "https://example.com/first-frame.jpg",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

### Multi-Reference Image Video

```json theme={null}
{
  "model": "omni-fast",
  "prompt": "Use the first image as the character reference and the second image as the visual style reference.",
  "images": [
    "https://example.com/character.jpg",
    "https://example.com/style.jpg"
  ],
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

## Notes

* `omni-fast` does not support the `video`, `video_url`, `input_video` reference-video fields.
* `images` supports up to 5 images.
* Image fields use JSON; multipart is not required.
* It is recommended to poll `GET /v1/videos/{task_id}`, and after completion retrieve the generated MP4 from the returned `video_url`.
* Reference-video editing or extension must use [`omni-fast-v2v`](./omni-fast-v2v).

## Related APIs

* [omni-fast-v2v](./omni-fast-v2v)
* [Omni Video Models Overview](./overview)
* [OpenAI Video Compatible API](/en/videos/openai-videos)
* [Task Status API](/en/tasks/task-status)