Videos

/v1/videos is an async video generation API. After creating a task, poll GET /v1/videos/{video_id} for status and progress, then download via GET /v1/videos/{video_id}/content when complete.

WARNING

The video API is asynchronous — it does not return the final content immediately like the text API.

Endpoints

• Create task: POST https://hboom.ai/v1/videos
• Poll progress: GET https://hboom.ai/v1/videos/{video_id}
• Download content: GET https://hboom.ai/v1/videos/{video_id}/content

Create a Video Task

Common Request Fields

Field	Required	Description
prompt	Yes	Video generation prompt
model	No	Video model, e.g. sora-2 or sora-2-pro, default sora-2
seconds	No	Duration: 4, 8, or 12, default 4
size	No	Resolution: 720x1280, 1280x720, 1024x1792, 1792x1024, default 720x1280
input_reference	No	Reference image object — provide image_url or file_id

cURL Example

curl https://hboom.ai/v1/videos \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "seconds=8" \
  -F "size=1280x720"

Node.js SDK Example

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxxxxxxxxx",
  baseURL: "https://hboom.ai/v1",
});

const video = await client.videos.create({
  model: "sora-2",
  prompt: "A calico cat playing a piano on stage",
  seconds: "8",
  size: "1280x720",
});

console.log(video);

Success Response Example

{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1280x720",
  "seconds": "8",
  "quality": "standard"
}

Poll Video Task Progress

Recommended polling interval: 10 to 20 seconds. progress is an approximate percentage; status is the task state.

Common Response Fields

Field	Description
id	Video task ID
object	Always video
status	Task state: queued, in_progress, completed, failed
progress	Approximate completion percentage
created_at	Task creation time (Unix timestamp, seconds)
completed_at	Completion time (present when done)
expires_at	Download expiry time (present when content is available)
prompt	The prompt for this task
error.code	Error code on failure
error.message	Error description on failure

Progress Response Examples

Queued:

{
  "id": "video_123",
  "object": "video",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "model": "sora-2",
  "seconds": "8",
  "size": "1280x720"
}

In progress:

{
  "id": "video_123",
  "object": "video",
  "status": "in_progress",
  "progress": 33,
  "created_at": 1712697600,
  "model": "sora-2",
  "seconds": "8",
  "size": "1280x720"
}

Completed:

{
  "id": "video_123",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "created_at": 1712697600,
  "completed_at": 1712697815,
  "expires_at": 1712701415,
  "model": "sora-2",
  "prompt": "A calico cat playing a piano on stage",
  "seconds": "8",
  "size": "1280x720"
}

Failed:

{
  "id": "video_123",
  "object": "video",
  "status": "failed",
  "progress": 12,
  "created_at": 1712697600,
  "model": "sora-2",
  "seconds": "8",
  "size": "1280x720",
  "error": {
    "code": "invalid_reference_image",
    "message": "Input images with human faces are currently rejected."
  }
}

Download Video Content

By default returns MP4 video. Use the variant query param for other formats:

Param	Description
variant=video	Download video file (default)
variant=thumbnail	Download thumbnail
variant=spritesheet	Download spritesheet

Download Video

curl https://hboom.ai/v1/videos/video_123/content \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  --output video.mp4

Download Thumbnail

curl "https://hboom.ai/v1/videos/video_123/content?variant=thumbnail" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
  --output thumbnail.webp

Optional: Webhook Callback

Instead of polling, configure a webhook to receive task result notifications. OpenAI video tasks trigger these events:

• video.completed
• video.failed

Example callback:

{
  "id": "evt_abc123",
  "object": "event",
  "created_at": 1758941485,
  "type": "video.completed",
  "data": {
    "id": "video_abc123"
  }
}

References

• OpenAI Video Generation Guide: https://platform.openai.com/docs/guides/video-generation/
• OpenAI Videos API Reference: https://developers.openai.com/api/reference/resources/videos/methods/create