> ## 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-v2v Reference Video Generation

> Call `omni-fast-v2v` via `POST /v1/videos` to edit, extend, or regenerate a reference video.

# omni-fast-v2v

`omni-fast-v2v` submits asynchronous video tasks with a JSON request body, suitable for editing, extending, or regenerating an existing MP4 as a reference video.

* Asynchronous processing mode; returns `id` or `task_id` after submission.
* The reference video field supports `video`, `video_url`, and `input_video`.
* The reference video supports a public MP4 URL or `data:video/mp4;base64,...`.
* The reference video is up to 15MB.
* When a reference video is not needed, prefer `omni-fast`.

## 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-v2v",
      "prompt": "Edit the attached video into a visibly new version while preserving the original camera path, timing, subject motion, and shot continuity. Add a rainy cinematic night look with neon reflections. Output a newly generated video, not the uploaded source clip or its preview.",
      "video": "https://example.com/source.mp4",
      "seconds": "8",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }'
  ```

  ```bash video_url alias 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-v2v",
      "prompt": "Extend this clip into a new cinematic shot with the same camera path.",
      "video_url": "https://example.com/source.mp4",
      "seconds": "8",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }'
  ```

  ```bash input_video alias 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-v2v",
      "prompt": "Regenerate the attached clip with brighter lighting and smoother motion.",
      "input_video": "https://example.com/source.mp4",
      "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-v2v",
          "prompt": "Edit the attached video into a visibly new version while preserving the original camera path. Output a newly generated video, not the uploaded source clip.",
          "video": "https://example.com/source.mp4",
          "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-v2v",
      prompt:
        "Edit the attached video into a visibly new version while preserving the original camera path. Output a newly generated video, not the uploaded source clip.",
      video: "https://example.com/source.mp4",
      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-v2v",
  		"prompt":       "Edit the attached video into a visibly new version while preserving the original camera path. Output a newly generated video, not the uploaded source clip.",
  		"video":        "https://example.com/source.mp4",
  		"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-v2v",
            "prompt": "Edit the attached video into a visibly new version while preserving the original camera path. Output a newly generated video, not the uploaded source clip.",
            "video": "https://example.com/source.mp4",
            "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-v2v',
      'prompt' => 'Edit the attached video into a visibly new version while preserving the original camera path. Output a newly generated video, not the uploaded source clip.',
      'video' => 'https://example.com/source.mp4',
      '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-v2v",
    "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-v2v",
    "status": "completed",
    "progress": 100,
    "created_at": 1735689600,
    "completed_at": 1735689900,
    "video_url": "https://example.com/results/omni-fast-v2v.mp4"
  }
  ```

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

  ```json 400 - Invalid Parameter theme={null}
  {
    "error": {
      "message": "video is required for V2V generation",
      "type": "invalid_request_error",
      "param": "video",
      "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 413 - Request Body Too Large theme={null}
  {
    "error": {
      "message": "request body too large",
      "type": "invalid_request_error",
      "code": "request_body_too_large"
    }
  }
  ```

  ```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-v2v`. Example: `"omni-fast-v2v"`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Video editing or generation prompt. It is recommended to state which motion, camera, or subject to preserve, and explicitly request a newly generated video. Example: `"Edit the attached video into a visibly new version"`.
</ParamField>

<ParamField body="video" type="string">
  Reference video. Supports a public MP4 URL or `data:video/mp4;base64,...`. Choose one of `video`, `video_url`, `input_video`. Example: `"https://example.com/source.mp4"`.
</ParamField>

<ParamField body="video_url" type="string">
  Compatibility field for `video`. Can be used when `video` is not provided. Example: `"https://example.com/source.mp4"`.
</ParamField>

<ParamField body="input_video" type="string">
  Compatibility field for `video`. Can be used when neither `video` nor `video_url` is provided. Example: `"https://example.com/source.mp4"`.
</ParamField>

<ParamField body="seconds" type="string">
  Output 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 field compatible with `omni-fast`. When there is no reference video, prefer `omni-fast`. Example: `"https://example.com/first-frame.jpg"`.
</ParamField>

<ParamField body="images" type="array<string>">
  Multi-reference image field compatible with `omni-fast`, up to 5. When there is no reference video, prefer `omni-fast`.
</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-v2v`.
</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

### Public MP4 Reference Video

```json theme={null}
{
  "model": "omni-fast-v2v",
  "prompt": "Extend this clip into a new cinematic shot with the same camera path.",
  "video": "https://example.com/source.mp4",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

### Local MP4 to data URI

```python theme={null}
import base64
from pathlib import Path

source = Path("source.mp4")
if source.stat().st_size > 15 * 1024 * 1024:
    raise ValueError("Reference video must be at most 15MB")

video = "data:video/mp4;base64," + base64.b64encode(source.read_bytes()).decode("ascii")
```

### Using the `input_video` alias

```json theme={null}
{
  "model": "omni-fast-v2v",
  "prompt": "Regenerate the attached clip with brighter lighting and smoother motion.",
  "input_video": "https://example.com/source.mp4",
  "seconds": "8",
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

## Notes

* `omni-fast` does not support reference video; V2V must use `omni-fast-v2v`.
* The reference video is up to 15MB; when too large, compress it first or convert to a public URL.
* `video`, `video_url`, `input_video` are the same kind of reference-video input; prefer `video`.
* For `data:video/mp4;base64,...`, the actual request body grows larger, so allow for network timeout.
* After completion, retrieve the generated MP4 from the returned `video_url`.

## Related APIs

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