Video Generation

POST /v1/videos

Create an asynchronous video generation task.

Create a new asynchronous video generation task.

Description

This endpoint starts a video generation job and returns a task object immediately. The task runs asynchronously, so you should poll the status endpoint until the task completes.

This endpoint is also available through the compatibility route POST /v1/openai/videos with identical behavior.

Content types

application/json
multipart/form-data

Use multipart/form-data when uploading an input_reference image for image-guided video generation.

Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the format `Bearer YOUR_API_KEY`.
`Content-Type`	string	Yes	`application/json` or `multipart/form-data`.

Request body parameters

Name	Type	Required	Description
`model`	string	Yes	Video model ID to use.
`prompt`	string	Yes	Text prompt describing the target video.
`size`	string	No	Output size such as `1280x720` or `720x1280`.
`seconds`	string / integer	No	Target video duration in seconds.
`input_reference`	file	No	Reference image file used as input for image-guided generation.
`stream`	boolean	No	Optional flag if supported by the selected model or upstream.

Example request

cURL (JSON)

curl https://api.apifree.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-model-id",
    "prompt": "A cinematic drone shot over a misty lake at sunrise",
    "size": "1280x720",
    "seconds": 8
  }'

cURL (Multipart)

curl https://api.apifree.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=video-model-id" \
  -F "prompt=A cinematic drone shot over a misty lake at sunrise" \
  -F "size=1280x720" \
  -F "seconds=8" \
  -F "input_reference=@/path/to/reference.png"

Response schema

A successful response returns a task object. Typical fields include:

Field	Type	Description
`id`	string	Video task ID.
`object`	string	Object type, typically `video`.
`created_at`	integer	Unix timestamp for task creation time.
`status`	string	Initial task status such as `queued` or `in_progress`.
`model`	string	Model used for generation.
`progress`	integer	Task progress percentage when available.
`seconds`	string / integer	Requested duration.
`size`	string	Requested output size.

Example response:

{
  "id": "video_abc123",
  "object": "video",
  "created_at": 1758941485,
  "status": "queued",
  "model": "video-model-id",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720"
}

Next step

After creating a task, call GET /v1/videos/{task_id} to monitor progress.

Errors

Typical error cases include:

Missing or invalid model
Missing prompt
Invalid JSON or multipart payload
Authentication failure
Upstream task creation failure