Video Generation API

Video generation always uses asynchronous tasks: submit POST /v1/videos, then poll GET /v1/videos/{task_id} for status and video URLs.

Images / Videos

This page documents video generation. For image generation, see Image Generation API. You can also compare against the online goswitch API docs.

Base Variables

All examples use BASE_URL as the site root. Do not include /v1 in this value. When you switch to another site, only change this variable.

bash

BASE_URL="https://goswitcher.com"
API_KEY="YOUR_API_KEY"

powershell

$BASE_URL = "https://goswitcher.com"
$API_KEY = "YOUR_API_KEY"

Which Endpoint To Use

Scenario	Mode	Model	Endpoint	Result
Omni text-to-video / image-to-video / video edit	Async	`omni_flash-10s` and other Omni models	`POST /v1/videos`	Returns a task ID, then use task query
Veo text-to-video / reference images / first-last frame	Async	`veo_3_1-fast`, `veo_3_1-fast-fl`, `veo_3_1-lite-fl`, and other Veo models	`POST /v1/videos`	Returns a task ID, then use task query
Task query	Shared query	Task ID	`GET /v1/videos/{task_id}`	Read video results from `url`, `video_url`, `content_url`, or `data[].video_url`

Current Implementation

/v1/videos is an asynchronous task endpoint. This page only documents Omni / Veo video models. Model availability follows site configuration and the online Apifox directory.

Authentication

Header	Required	Notes
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	Use `application/json` for JSON requests; use `multipart/form-data` for file upload requests

Base URL

BASE_URL is the site root, for example https://goswitcher.com. Do not set it to https://goswitcher.com/v1 and then append /v1/videos, or the path will contain /v1 twice.

Endpoint Details

Omni Async Video

Item	Value
Method	`POST`
Path	`/v1/videos`
Content-Type	`application/json` or `multipart/form-data`
Result	Task object. Continue with task query

Request Parameters

Parameter	Type	Required	Notes
`model`	string	Yes	For example `omni_flash-10s`; check Apifox for more tiers
`prompt`	string	Yes	Video prompt
`size`	string	No	Video size, such as `1280x720` or `720x1280`
`images`	string[]	No	For JSON requests. Use URL / Data URL references for image-to-video or video edit, up to 7 items. Do not use `input_reference` in JSON
`input_reference`	file or string, repeatable	No	For multipart requests. Use local image, local video, image URL, video URL, or Data URL references, up to 7 items
`n`	integer	No	Video models only support `1` or omitted; `n > 1` returns an error

Call Examples

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash-10s",
    "prompt": "Create a 10-second product advertising video with a slow push-in camera move and clean background",
    "size": "1280x720",
    "images": [
      "https://example.com/reference-1.jpg"
    ]
  }'

powershell

$body = @{
  model = "omni_flash-10s"
  prompt = "Create a 10-second product advertising video with a slow push-in camera move and clean background"
  size = "1280x720"
  images = @("https://example.com/reference-1.jpg")
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/videos" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -ContentType "application/json" `
  -Body $body

const response = await fetch(`${BASE_URL}/v1/videos`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'omni_flash-10s',
    prompt: 'Create a 10-second product advertising video with a slow push-in camera move and clean background',
    size: '1280x720',
    images: ['https://example.com/reference-1.jpg'],
  }),
})

console.log(await response.json())

import axios from 'axios'

const { data } = await axios.post(`${BASE_URL}/v1/videos`, {
  model: 'omni_flash-10s',
  prompt: 'Create a 10-second product advertising video with a slow push-in camera move and clean background',
  size: '1280x720',
  images: ['https://example.com/reference-1.jpg'],
}, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

console.log(data)

python

import requests

resp = requests.post(
    f"{BASE_URL}/v1/videos",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "omni_flash-10s",
        "prompt": "Create a 10-second product advertising video with a slow push-in camera move and clean background",
        "size": "1280x720",
        "images": ["https://example.com/reference-1.jpg"],
    },
)
print(resp.json())

body, _ := json.Marshal(map[string]any{
	"model":  "omni_flash-10s",
	"prompt": "Create a 10-second product advertising video with a slow push-in camera move and clean background",
	"size":   "1280x720",
	"images": []string{"https://example.com/reference-1.jpg"},
})
req, _ := http.NewRequest("POST", BASE_URL+"/v1/videos", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+API_KEY)
req.Header.Set("Content-Type", "application/json")

Omni multipart reference / video edit

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  --form 'model="omni_flash-10s"' \
  --form 'prompt="Create a product advertising video using the reference asset"' \
  --form 'size="1280x720"' \
  --form 'input_reference=@"/path/to/reference.jpg"'

The input_reference field can be repeated. For video edit, submit a local video with input_reference=@"/path/to/input.mp4" and describe the edit in prompt.

Veo Async Video

Item	Value
Method	`POST`
Path	`/v1/videos`
Content-Type	`application/json` or `multipart/form-data`
Result	Task object. Continue with task query

Models And Modes

Mode	Example model	Notes
Text-to-video	`veo_3_1-fast`	Generate from prompt only
Reference image mode	`veo_3_1-fast`	Supports up to 3 reference images
First-last frame mode	`veo_3_1-fast-fl`, `veo_3_1-lite-fl`	First image is the first frame, second image is the last frame; one image means first frame only
Official ID compatibility	`veo-3.0-generate-001`, `veo-3.1-generate-preview`	Current switcher local adapter also supports these upstream model IDs

Request Parameters

Parameter	Type	Required	Notes
`model`	string	Yes	Veo model name. Availability can change with site configuration and upstream capacity
`prompt`	string	Yes	Video prompt
`size`	string	No	Video size, such as `1280x720` or `1920x1080`
`images`	string[]	No	For JSON requests. Each item is an image URL or Data URL
`input_reference`	file or string, repeatable	No	For multipart requests. Use local image, image URL, or Data URL
`n`	integer	No	Video models only support `1` or omitted; `n > 1` returns an error

Call Examples

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo_3_1-lite-fl",
    "prompt": "Use the first frame to create a natural product showcase video with a stable push-in camera move",
    "size": "1280x720",
    "images": [
      "https://example.com/first-frame.jpg"
    ]
  }'

powershell

$body = @{
  model = "veo_3_1-lite-fl"
  prompt = "Use the first frame to create a natural product showcase video with a stable push-in camera move"
  size = "1280x720"
  images = @("https://example.com/first-frame.jpg")
} | ConvertTo-Json

Invoke-RestMethod -Method Post `
  -Uri "$BASE_URL/v1/videos" `
  -Headers @{ Authorization = "Bearer $API_KEY" } `
  -ContentType "application/json" `
  -Body $body

const response = await fetch(`${BASE_URL}/v1/videos`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'veo_3_1-lite-fl',
    prompt: 'Use the first frame to create a natural product showcase video with a stable push-in camera move',
    size: '1280x720',
    images: ['https://example.com/first-frame.jpg'],
  }),
})

console.log(await response.json())

const { data } = await axios.post(`${BASE_URL}/v1/videos`, {
  model: 'veo_3_1-lite-fl',
  prompt: 'Use the first frame to create a natural product showcase video with a stable push-in camera move',
  size: '1280x720',
  images: ['https://example.com/first-frame.jpg'],
}, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})

python

resp = requests.post(
    f"{BASE_URL}/v1/videos",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo_3_1-lite-fl",
        "prompt": "Use the first frame to create a natural product showcase video with a stable push-in camera move",
        "size": "1280x720",
        "images": ["https://example.com/first-frame.jpg"],
    },
)
print(resp.json())

body, _ := json.Marshal(map[string]any{
	"model":  "veo_3_1-lite-fl",
	"prompt": "Use the first frame to create a natural product showcase video with a stable push-in camera move",
	"size":   "1280x720",
	"images": []string{"https://example.com/first-frame.jpg"},
})
req, _ := http.NewRequest("POST", BASE_URL+"/v1/videos", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+API_KEY)
req.Header.Set("Content-Type", "application/json")

Veo first-last frame multipart example

bash

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $API_KEY" \
  --form 'model="veo_3_1-fast-fl"' \
  --form 'prompt="Transition naturally from the first frame to the last frame while preserving the subject"' \
  --form 'size="1280x720"' \
  --form 'input_reference=@"/path/to/first-frame.jpg"' \
  --form 'input_reference=@"/path/to/last-frame.jpg"'

Reference-image mode supports up to 3 images. First-last frame mode usually uses 1 to 2 images. Pure JSON requests cannot include local files; use public URLs or full Data URLs in images.

Task Query

Item	Value
Method	`GET`
Path	`/v1/videos/{task_id}`
Use	Query video asynchronous tasks

Path Parameters

Parameter	Type	Required	Notes
`task_id`	string	Yes	The `id` returned by the submit endpoint; some upstreams may return `task_id`

Status Fields

status	Client behavior
`queued`	The task is queued. Continue polling
`processing`	The task is processing. Continue polling
`in_progress`	The task is processing. Continue polling
`running`	The task is processing. Continue polling
`completed`	The task is complete. Read video result URLs
`failed`	The task failed. Read `error` or `error.message`

Poll every 5 seconds or so. Video tasks usually take longer than image tasks, so clients should use a longer timeout.

Result Fields

After completion, read video URLs from these fields first: video_url, url, content_url, metadata.video_url, metadata.url, data[].video_url, data[].url, videos[].url.

Call Examples

bash

TASK_ID="task_xxxxxxxxxxxxx"

curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

powershell

$TASK_ID = "task_xxxxxxxxxxxxx"

Invoke-RestMethod -Method Get `
  -Uri "$BASE_URL/v1/videos/$TASK_ID" `
  -Headers @{ Authorization = "Bearer $API_KEY" }

const taskId = 'task_xxxxxxxxxxxxx'
const response = await fetch(`${BASE_URL}/v1/videos/${taskId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})
console.log(await response.json())

const taskId = 'task_xxxxxxxxxxxxx'
const { data } = await axios.get(`${BASE_URL}/v1/videos/${taskId}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
})
console.log(data)

python

task_id = "task_xxxxxxxxxxxxx"
resp = requests.get(
    f"{BASE_URL}/v1/videos/{task_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
print(resp.json())

taskID := "task_xxxxxxxxxxxxx"
req, _ := http.NewRequest("GET", BASE_URL+"/v1/videos/"+taskID, nil)
req.Header.Set("Authorization", "Bearer "+API_KEY)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Video task response examples

json

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "omni_flash-10s",
  "status": "queued",
  "progress": 0,
  "created_at": 1709876543,
  "size": "1280x720"
}

json

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "veo_3_1-lite-fl",
  "status": "completed",
  "progress": 100,
  "created_at": 1709876543,
  "completed_at": 1709876600,
  "size": "1280x720",
  "video_url": "https://example.com/output.mp4"
}

json

{
  "id": "task_xxxxxxxxxxxxx",
  "object": "video",
  "model": "veo_3_1-lite-fl",
  "status": "failed",
  "progress": 100,
  "error": {
    "message": "Upstream task failed",
    "code": "upstream_error"
  }
}

Common Notes

Video generation is always asynchronous. It does not return the final asset directly like the synchronous image2 image endpoint.
Video models do not support local batch n > 1; submit multiple tasks from the client if you need multiple videos.
JSON requests use images for reference URLs / Data URLs; multipart requests use repeatable input_reference fields for files or text references.
Reference image and video URLs must be directly reachable by the server. Login-only pages, intranet URLs, and local file paths usually cannot be fetched by the server.
Model availability can change with site configuration, upstream capacity, and safety controls. Production integrations should implement fallback logic for unavailable models.
Generated result URLs may expire, so download and store results soon after task completion.

Video Generation API ​

Base Variables ​

Which Endpoint To Use ​

Authentication ​

Endpoint Details ​

Omni Async Video ​

Request Parameters ​

Call Examples ​

Veo Async Video ​

Models And Modes ​

Request Parameters ​

Call Examples ​

Task Query ​

Path Parameters ​

Status Fields ​

Result Fields ​

Call Examples ​

Common Notes ​

Video Generation API

Base Variables

Which Endpoint To Use

Authentication

Endpoint Details

Omni Async Video

Request Parameters

Call Examples

Veo Async Video

Models And Modes

Request Parameters

Call Examples

Task Query

Path Parameters

Status Fields

Result Fields

Call Examples

Common Notes