Skip to main content
POST
/
api
/
v1
/
video
Generate Video
curl --request POST \
  --url https://api.example.com/api/v1/video \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "duration": "<string>",
  "style": "<string>"
}
'
{
  "id": "<string>",
  "job_id": "<string>",
  "status": "<string>",
  "created": "<string>",
  "poll_url": "<string>"
}
Generate video from a text prompt. This is an asynchronous endpoint — it returns a job ID immediately (HTTP 202) and the video is generated in the background.
Video generation is async. Poll the job status with Get Job Status or use theo.waitForJob() in the SDK.
AI-disclosure watermark. Every video returned from Theo carries a small, semi-transparent Theo logo in the bottom-right corner. This is a provenance signal that identifies the clip as AI-generated and is always applied (regardless of any branding preference). Expect +2–15 seconds of re-encode latency per clip.

​
Authentication

Requires a Bearer token. See Authentication.

​
Request Body

​
prompt
string
required
Text description of the video to generate.
​
duration
string
Target video duration (e.g., "5s", "10s", "15s").
​
style
string
Visual style (e.g., "cinematic", "animation", "timelapse").

​
Request Examples

curl -X POST https://www.hitheo.ai/api/v1/video \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 5-second animation of a rocket launch",
    "duration": "5s",
    "style": "cinematic"
  }'

​
Response (HTTP 202)

​
id
string
Unique video request ID (prefixed vid_).
​
job_id
string
Job ID for polling status.
​
status
string
Always "queued" on creation.
​
created
string
ISO 8601 timestamp.
​
poll_url
string
Relative URL to poll for job status (e.g., /api/v1/jobs/{job_id}).

​
Example Response

{
  "id": "vid_abc123",
  "job_id": "job_xyz789",
  "status": "queued",
  "created": "2026-04-10T12:00:00Z",
  "poll_url": "/api/v1/jobs/job_xyz789"
}

​
Polling for Results

Use the Get Job Status endpoint to check progress. When status is "completed", the result field contains the video URL. 
curl https://www.hitheo.ai/api/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer $THEO_API_KEY"

​
Errors

StatusCodeDescription
400missing_promptprompt is required
401invalid_api_keyMissing or invalid API key
503queue_unavailableVideo generation queue is not available — retry later