Videos API

Create, poll, and download asynchronous video tasks

Video generation uses an async task model: create → poll status → download result. The gateway provides two create paths; query and download endpoints are shared.

1. Overview

Async flow

Create task → Poll GET /v1/videos/{task_id} → Download GET /v1/videos/{task_id}/content

Call POST /v1/videos or POST /v1/guidai/videos to submit a task and receive a task_id
Poll GET /v1/videos/{task_id} until status is completed or failed
After completion, download via GET /v1/videos/{task_id}/content; optionally use ?variant=thumbnail for the cover image

Comparing the two create paths

Item	`POST /v1/videos`	`POST /v1/guidai/videos`
Use case	General video create; fields follow upstream video model conventions	Multimodal video generation via `mode` + `assets[]`
Content-Type	`application/json` or `multipart/form-data`	`application/json`
Core params	`model`, `prompt`, `size`, `seconds`, `input_reference`	`model`, `mode`, `prompt`, `assets[]`, `resolution`, `duration_sec`, etc.
Reference image	JSON URL / Base64 data URI / multipart file upload	Pass URLs in `assets[]` by `role`
Generation mode	No `mode` field; determined by model and request fields	Explicit `mode`: `t2v`, `i2v`, `first_frame`, `first_last_frame`, `ref_image`, `video_extend`, `video_edit`
Query & download	`GET /v1/videos/{task_id}`, `GET /v1/videos/{task_id}/content`	Same (shared)

Prerequisite: model must be a model from the Models API whose supported_endpoint_types includes openai-video.

2. Endpoints

Method	Path	Description
POST	`/v1/videos`	Create video task (general)
GET	`/v1/videos/{task_id}`	Query task status
GET	`/v1/videos/{task_id}/content`	Download video or thumbnail
POST	`/v1/guidai/videos`	Create video task (multimodal / Guid AI)

3. Task status

Item	Description
Task ID format	Public ID shaped like `task_xxxxxxxx`
Status flow	`queued` → `in_progress` → `completed` / `failed`

`status`	Description
`queued`	Queued
`in_progress`	Generating
`completed`	Completed; ready to download
`failed`	Failed; see the `error` field

4. POST `/v1/videos`

Create a video task.

Auth: Bearer Token

Content-Type: application/json or multipart/form-data

Request body (JSON)

{
  "model": "sora-2",
  "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting",
  "size": "1280x720",
  "seconds": 8
}

Request fields

Field	Type	Required	Description
`model`	string	Yes	Video model name
`prompt`	string	Yes	Video description (≤ 2500 characters)
`size`	string	Conditional	Resolution, e.g. `1280x720`, `720x1280`; required for models such as sora-2
`seconds`	int / string	Conditional	Duration in seconds; sora-2 allows `4/8/12/16/20`
`input_reference`	object / file	No	Reference image

With reference image (JSON URL):

{
  "model": "sora-2",
  "prompt": "Animate this image with a slight camera move",
  "size": "1280x720",
  "seconds": 8,
  "input_reference": {
    "image_url": "https://example.com/ref.jpg"
  }
}

With reference image (Base64 data URI):

{
  "model": "sora-2",
  "prompt": "Animate this image with a slight camera move",
  "size": "1280x720",
  "seconds": 8,
  "input_reference": {
    "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

multipart/form-data: input_reference is a file form field; other fields use the same names.

Request example (curl)

JSON:

curl https://www.guid.ai/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting",
    "size": "1280x720",
    "seconds": 8
  }'

With reference image (JSON):

curl https://www.guid.ai/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "Animate this image with a slight camera move",
    "size": "1280x720",
    "seconds": 8,
    "input_reference": {
      "image_url": "https://example.com/ref.jpg"
    }
  }'

multipart/form-data (upload reference image):

curl https://www.guid.ai/v1/videos \
  -H "Authorization: Bearer sk-xxx" \
  -F "model=sora-2" \
  -F "prompt=Animate this image with a slight camera move" \
  -F "size=1280x720" \
  -F "seconds=8" \
  -F "input_reference=@/path/to/ref.jpg"

Response body

HTTP 200

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

Response fields

Field	Type	Description
`id`	string	Task ID for query and download
`status`	string	Initially `queued`
`progress`	integer	Progress 0–100
`created_at`	integer	Unix timestamp (seconds)

Failure response

HTTP 400

{
  "code": "invalid_request",
  "message": "seconds must be one of 4, 8, 12, 16, 20"
}

Field	Type	Description
`code`	string	Error code
`message`	string	Validation failure reason

See Task errors for the error format.

5. GET `/v1/videos/{task_id}`

Query video task status.

Auth: Bearer Token

Path parameter: task_id — the id returned when creating the task

Request: No request body

Request example (curl)

curl https://www.guid.ai/v1/videos/task_abc123xyz \
  -H "Authorization: Bearer sk-xxx"

Response body (in progress)

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1712697600,
  "seconds": "5.0",
  "size": "1280x704"
}

Response body (completed)

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712698200,
  "seconds": "5.0",
  "size": "1280x704",
  "remixed_from_video_id": "https://cdn.example.com/videos/video_abc.mp4",
  "error": null,
  "metadata": {
    "url": "https://cdn.example.com/videos/video_abc.mp4"
  }
}

Response body (failed)

HTTP 200

{
  "id": "task_abc123xyz",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "failed",
  "progress": 100,
  "created_at": 1712697600,
  "error": {
    "message": "upstream generation failed",
    "code": "generation_failed"
  }
}

Response fields

Field	Type	Description
`id`	string	Task ID; same as the create response `id`
`object`	string	Always `video`
`model`	string	Model used
`status`	string	Task status; see Task status
`progress`	integer	Progress 0–100
`created_at`	integer	Created-at Unix timestamp (seconds)
`completed_at`	integer	Completed-at Unix timestamp (seconds); omitted while incomplete
`expires_at`	integer	Result expiry Unix timestamp (seconds); returned by some channels
`seconds`	string	Video duration in seconds, e.g. `"5.0"`
`size`	string	Video resolution, e.g. `"1280x704"`
`remixed_from_video_id`	string	Video result URL; some channels (e.g. Agnes AI) return a CDN address here
`error`	object / null	Error info on failure; `null` or omitted on success
`error.message`	string	Failure reason
`error.code`	string	Error code, e.g. `generation_failed`
`metadata`	object	Extended metadata; common keys below

Common metadata keys:

Key	Type	Description
`url`	string	Video result URL
`thumbnail_url`	string	Thumbnail URL
`duration`	number	Actual duration (seconds)
`width`	integer	Video width (pixels)
`height`	integer	Video height (pixels)
`fps`	integer	Frame rate
`seed`	integer	Random seed

6. GET `/v1/videos/{task_id}/content`

Download the generated video or thumbnail.

Auth: Bearer Token or admin console Session

Path parameter: task_id

Query parameters:

Parameter	Description
`variant`	Optional. `video` (default) downloads the video; `thumbnail` downloads the cover image

Prerequisite: Task status must be completed.

Request example (curl)

Download video (follow 301 redirect):

curl -L https://www.guid.ai/v1/videos/task_abc123xyz/content \
  -H "Authorization: Bearer sk-xxx" \
  -o output.mp4

Download thumbnail:

curl -L "https://www.guid.ai/v1/videos/task_abc123xyz/content?variant=thumbnail" \
  -H "Authorization: Bearer sk-xxx" \
  -o cover.jpg

Response (already stored in object storage)

HTTP 301 Moved Permanently

Location: https://cdn.example.com/users/1/tasks/task_abc123xyz/video.mp4

Header / field	Description
`Location`	Object storage or CDN resource URL; clients should follow the redirect
Body	No JSON content

Response (gateway proxies upstream)

HTTP 200, body is a binary stream (not JSON).

Header	Description
`Content-Type`	`video/mp4` (video) or `image/jpeg` / `image/png` (thumbnail)
`Content-Length`	File size in bytes
`Content-Disposition`	May include filename, e.g. `attachment; filename="task_abc123xyz.mp4"`
Body	Video or thumbnail binary data

Error responses

Task not completed yet, HTTP 400:

{
  "error": {
    "message": "Task is not completed yet, current status: in_progress",
    "type": "invalid_request_error"
  }
}

Task not found, HTTP 404:

{
  "error": {
    "message": "Task not found",
    "type": "invalid_request_error"
  }
}

Invalid variant, HTTP 400:

{
  "error": {
    "message": "invalid variant \"cover\", must be \"video\" or \"thumbnail\"",
    "type": "invalid_request_error"
  }
}

Thumbnail unavailable, HTTP 404:

{
  "error": {
    "message": "Thumbnail not available",
    "type": "invalid_request_error"
  }
}

See Standard errors for the error format.

7. POST `/v1/guidai/videos`

Multimodal video generation. Specify the generation mode with mode, and pass image/video URLs via assets[].

After a successful submit, query with GET /v1/videos/{task_id} and download with GET /v1/videos/{task_id}/content.

Auth: Bearer Token

Content-Type: application/json

Generation modes (`mode`)

`mode`	Description	Typical required assets
`t2v`	Text-to-video	None
`i2v`	Image-to-video	`image`
`first_frame`	First-frame to video	`first_frame`
`first_last_frame`	First and last frame to video	`first_frame`, `last_frame`
`ref_image`	Reference-image to video	At least one `reference_images`
`video_extend`	Video extend / continue	`source_video`
`video_edit`	Smart video edit	`source_video`; optional `reference_images`

Enabled mode values per model follow the admin console Model capabilities → Video capabilities configuration.

Request fields

Field	Type	Required	Description
`model`	string	Yes	Video model
`mode`	string	Yes	Generation mode
`prompt`	string	Conditional	Video description; required for most modes
`assets`	array	Conditional	`[{ "role": "...", "url": "https://..." }]`
`resolution`	string	No	e.g. `720p`, `1080p`
`duration_sec`	number	No	Duration (seconds)
`aspect_ratio`	string	No	e.g. `16:9`, `3:2`
`prompt_optimize`	boolean	No	Whether to enable prompt optimization
`gen_tier`	string	No	Generation tier
`quality`	string	No	Quality
`audio_mode`	string	No	Audio mode
`camera_control`	string	No	Camera control
`shot_type`	string	No	Shot type
`hd_upscale`	string	No	HD upscale

Request example: text-to-video (t2v)

{
  "model": "agnes-video-v2.0",
  "mode": "t2v",
  "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
  "resolution": "720p",
  "duration_sec": 5,
  "aspect_ratio": "3:2",
  "prompt_optimize": false
}

Request example: first-frame to video (first_frame)

{
  "model": "agnes-video-v2.0",
  "mode": "first_frame",
  "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
  "assets": [
    { "role": "first_frame", "url": "https://example.com/image.png" }
  ],
  "duration_sec": 5
}

Request example: reference-image to video (ref_image)

{
  "model": "agnes-video-v2.0",
  "mode": "ref_image",
  "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
  "assets": [
    { "role": "reference_images", "url": "https://example.com/image1.png" },
    { "role": "reference_images", "url": "https://example.com/image2.png" }
  ],
  "duration_sec": 5
}

Request example: video extend (video_extend)

{
  "model": "wan2.6-t2v",
  "mode": "video_extend",
  "prompt": "Continue the scene with the character walking into the sunset",
  "assets": [
    { "role": "source_video", "url": "https://example.com/source.mp4" }
  ],
  "duration_sec": 5,
  "resolution": "720p"
}

Request example (curl)

Text-to-video (t2v):

curl https://www.guid.ai/v1/guidai/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "t2v",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
    "resolution": "720p",
    "duration_sec": 5,
    "aspect_ratio": "3:2",
    "prompt_optimize": false
  }'

First-frame to video (first_frame):

curl https://www.guid.ai/v1/guidai/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "first_frame",
    "prompt": "The woman slowly turns around and looks back at the camera, natural facial expression, cinematic camera movement",
    "assets": [
      {"role": "first_frame", "url": "https://example.com/image.png"}
    ],
    "duration_sec": 5
  }'

Reference-image to video (ref_image):

curl https://www.guid.ai/v1/guidai/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "mode": "ref_image",
    "prompt": "Create a smooth transformation scene between the two reference images, cinematic lighting, consistent character identity, natural motion",
    "assets": [
      {"role": "reference_images", "url": "https://example.com/image1.png"},
      {"role": "reference_images", "url": "https://example.com/image2.png"}
    ],
    "duration_sec": 5
  }'

Video extend (video_extend):

curl https://www.guid.ai/v1/guidai/videos \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "mode": "video_extend",
    "prompt": "Continue the scene with the character walking into the sunset",
    "assets": [
      {"role": "source_video", "url": "https://example.com/source.mp4"}
    ],
    "duration_sec": 5,
    "resolution": "720p"
  }'

Response body

HTTP 200

{
  "id": "task_abc123xyz",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600
}

Response fields

Same as the POST /v1/videos create response.

Field	Type	Description
`id`	string	Task ID for later query and download
`status`	string	Initially `queued`
`progress`	integer	Progress 0–100
`created_at`	integer	Created-at Unix timestamp (seconds)

Subsequent query and download use GET /v1/videos/{task_id} and GET /v1/videos/{task_id}/content. Response fields are in Section 5 and Section 6.

Failure response

HTTP 400

{
  "code": "invalid_request",
  "message": "model and mode are required"
}

{
  "code": "invalid_request",
  "message": "prompt is required"
}

See Task errors for the error format.

8. Recommended async video flow

1. POST /v1/videos or POST /v1/guidai/videos
   → obtain task_id

2. Poll GET /v1/videos/{task_id}
   → continue waiting while status = queued / in_progress
   → inspect error when status = failed
   → proceed when status = completed

3. GET /v1/videos/{task_id}/content
   → download the video file

4. (Optional) GET /v1/videos/{task_id}/content?variant=thumbnail
   → download the thumbnail

Suggested polling interval: 3–10 seconds, to avoid rate limiting from overly frequent requests.

Images API

Text-to-image and image-to-image/edit; synchronously returns image URLs or Base64 data

Audio API

Text-to-speech (TTS) and voice list queries