Skip to main content
POST
/
v1
/
videos
cURL
curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F model=veo3.1-fast \
  -F 'prompt=A paper kite floats above a field.' \
  -F seconds=4 \
  -F size=1280x720
{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "veo3.1-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1779938152
}
Use this endpoint to start a Veo 3.1 video task. The API returns a task ID immediately, so store the returned id and poll the task until it reaches a terminal status. POST /v1/videos uses multipart/form-data; pass scalar controls as form fields and media inputs as input_reference file fields.

​
Choose a model

Model IDWhen to use itNotes
veo3.1-fastDefault choice for most short clipsFaster Veo 3.1 route.
veo3.1Use when you specifically want the standard Veo 3.1 modelStandard Veo 3.1 route.

​
Choose an input mode

GoalRequired fieldsOptional fields
Text-to-videomodel, promptseconds, size
Image-to-videomodel, prompt, input_referenceseconds, size

​
Set duration and size

For the OpenAI-compatible route, use seconds for duration and size for the output size. Send values as form fields.
Model IDsecondsDefault
veo3.1-fast4, 6, 84 seconds, 1280x720
veo3.14, 6, 84 seconds, 1280x720
Set size to one of the WxH values below.
Resolution tierAspect ratiosize (WxH)
720p16:91280x720
9:16720x1280
1080p16:91920x1080
4K16:93840x2160

​
Task flow

1

Create the task

Send the multipart form request and store the returned id.
2

Poll the task

Use Veo3 Retrieve until status is completed, failed, or error.
3

Download the result

When the task is completed, download the MP4 file from the completed task response.

Authorizations

​
Authorization
string
header
required

Bearer authentication. Use your CometAPI API key.

Body

multipart/form-data
​
model
enum<string>
required

Veo 3.1 model ID. Use veo3.1-fast for the default route or veo3.1 when you specifically need the standard model.

Available options:
veo3.1-fast,
veo3.1
Example:

"veo3.1-fast"

​
prompt
string
required

Text prompt for the video job.

Example:

"A paper kite floats above a field."

​
seconds
enum<string>
default:4

Requested clip duration. Use 4, 6, or 8. Send the value as a form field string.

Available options:
4,
6,
8
Example:

"4"

​
size
string

Supported WxH size values: 1280x720, 720x1280, 1920x1080, 3840x2160. Default is 1280x720.

Example:

"1280x720"

​
input_reference
file

Optional first-frame image file for image-to-video.

Response

Task created. Store the returned id and poll GET /v1/videos/{task_id}.

​
id
string
required

Task ID. Use this value with retrieve and content endpoints.

Example:

"task_example"

​
object
string
required

Object type. Video tasks return video.

Example:

"video"

​
model
string
required

Model ID used for the task.

Example:

"veo3.1-fast"

​
status
enum<string>
required

Task lifecycle status. Poll until the value is completed, failed, or error.

Available options:
queued,
in_progress,
completed,
failed,
error
Example:

"queued"

​
progress
integer
required

Task progress as a coarse percentage.

Required range: 0 <= x <= 100
Example:

0

​
created_at
integer
required

Task creation time as a Unix timestamp in seconds.

Example:

1779938152

​
task_id
string

Compatibility alias for id when present.

Example:

"task_example"

​
completed_at
integer

Task completion time as a Unix timestamp in seconds. This field appears on completed tasks.

Example:

1779938219

​
video_url
string

Temporary video delivery URL. This field appears on completed tasks.

Example:

"<temporary-video-url>"

​
error
object

Failure details. This field appears when the task fails.