Video Generation

Generate videos from text prompts, images, or other videos

Endpoint

POST /api/videos/generate

Generates videos synchronously. The request blocks until the video is ready, which can take 1-10+ minutes depending on the model and duration.

For long-running or batch generation, consider using the async queue instead.

Request Parameters

Parameter	Type	Required	Default	Description
model	string	yes	—	Video model name (e.g. kling-video-v2-6-pro-text-to-video, kling-video-o3-pro-reference-to-video)
prompt	string	one of	—	Text prompt. Use this or multi_prompt, not both.
multi_prompt	array	one of	—	Multi-shot prompts with per-shot duration. See Kling O3 Pro reference for details.
duration	integer	no	5	Video duration in seconds (when using prompt).
aspect_ratio	string	no	"16:9"	Aspect ratio (e.g. "16:9", "9:16", "1:1").
input_image	string/array	no	—	Reference image(s) for image-to-video or reference-to-video models.
input_video	string (URL)	no	—	Reference video for video-to-video models.
generate_audio	boolean	no	false	Generate audio track (model-dependent).
response_format	string	no	"url"	"url" returns a hosted URL. "b64_json" returns base64-encoded video bytes inline.
target_namespace	string	no	current user	Namespace to save results and bill to. Can be an organization name.

Additional parameters vary by model. Use the model detail endpoint (GET /api/evaluations/models/:id) to see the json_request_schema for model-specific parameters.

Either prompt or multi_prompt is required. Sending both returns an error:

"Cannot provide both 'prompt' and 'multi_prompt'."

Sending neither returns:

"Either 'prompt' or 'multi_prompt' must be provided."

Examples

Basic text-to-video

Python

import requests

response = requests.post(
    "https://hub.oxen.ai/api/videos/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-video-v2-6-pro-text-to-video",
        "prompt": "A red balloon floating upward through blue sky",
        "duration": 5,
    },
)

data = response.json()
print("Video URL:", data["videos"][0]["url"])

Response (response_format: "url")

{
  "model": "kling-video-v2-6-pro-text-to-video",
  "created": 1775090508,
  "videos": [
    {
      "url": "https://hub.oxen.ai/api/repos/.../files/.../video.mp4?..."
    }
  ]
}

The URL is a temporary link that expires after a period of time.

Response (response_format: "b64_json")

{
  "model": "kling-video-v2-6-pro-text-to-video",
  "created": 1775090508,
  "videos": [
    {
      "b64_json": "<base64-encoded mp4 bytes>"
    }
  ]
}

Multi-shot video

Python

import requests

response = requests.post(
    "https://hub.oxen.ai/api/videos/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-video-o3-pro-reference-to-video",
        "multi_prompt": [
            {"prompt": "Wide shot: a bird takes off from a branch", "duration": 5},
            {"prompt": "Tracking shot: the bird soars through clouds", "duration": 5},
        ],
        "aspect_ratio": "16:9",
    },
)

data = response.json()
print("Video URL:", data["videos"][0]["url"])

Important Notes

• Video generation can take several minutes. Very long generations may time out on your client side.
• For long-running or batch generation, use /ai/queue which returns immediately and processes in the background.

Errors

Condition	Error
Both prompt and multi_prompt	"Cannot provide both 'prompt' and 'multi_prompt'."
Neither prompt nor multi_prompt	"Either 'prompt' or 'multi_prompt' must be provided."
Model not found	"Model not found: <name>"