Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oxen.ai/llms.txt

Use this file to discover all available pages before exploring further.

Edit existing videos using text instructions. Describe what to change — add objects, swap characters, alter scenery — and the model re-renders the video accordingly. Supports reference images (@Image1, @Image2, …) and structured element references (@Element1, @Element2, …) for character/object consistency across the edit. Model name: kling-video-o3-pro-video-to-video-edit

​
Endpoint

POST /api/ai/videos/generate
Video editing is synchronous — the request blocks until the edited video is ready (typically 1–5 minutes). It is recommended to use /ai/queue instead for long-running jobs, so that you don’t have long running http requests.

​
Request Parameters

ParameterTypeRequiredDefaultDescription
modelstringyes—"kling-video-o3-pro-video-to-video-edit"
promptstringyes—Text description of what to generate or how to edit the video.
input_videostring (URI)yes—URL of the source video to edit.
input_imagearray of URIsno—Reference images for style/appearance. Use @Image1, @Image2, etc. in the prompt to refer to them.
elementsarray of objectsno—Structured element references for characters/objects. See elements below.
keep_audiobooleannofalseWhether to keep the original audio from the source video.
response_formatstringno"url""url" returns a hosted URL. "b64_json" returns base64-encoded video bytes inline.
target_namespacestringnocurrent userNamespace to save results and bill to. Can be an organization name.

​
elements

Array of element objects for character/object reference. Use @Element1, @Element2, etc. in prompts.
FieldTypeRequiredDescription
frontal_image_urlstring (URI)yesFront view of the reference object or character.
reference_image_urlsarray of URIsnoAdditional angles. Max 3 images per element.

​
Examples

​
Basic video edit

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/videos/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-video-o3-pro-video-to-video-edit",
        "prompt": "A red bird flies in and lands in-between the two birds on the wire",
        "input_video": "https://example.com/birds-on-wire.mp4",
    },
)

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

​
Edit with reference images

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/videos/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-video-o3-pro-video-to-video-edit",
        "prompt": "Replace the person with @Image1 walking in the same direction",
        "input_video": "https://example.com/street-scene.mp4",
        "input_image": ["https://example.com/character-reference.jpg"],
    },
)

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

​
Edit with elements and keep audio

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/videos/generate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-video-o3-pro-video-to-video-edit",
        "prompt": "@Element1 replaces the main character in the scene",
        "input_video": "https://example.com/original-scene.mp4",
        "elements": [
            {
                "frontal_image_url": "https://example.com/character-front.jpg",
                "reference_image_urls": [
                    "https://example.com/character-side.jpg",
                    "https://example.com/character-back.jpg",
                ],
            }
        ],
        "keep_audio": True,
    },
)

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

​
Response (response_format: "url")

{
  "created": 1775090723,
  "model": "kling-video-o3-pro-video-to-video-edit",
  "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")

{
  "created": 1775090723,
  "model": "kling-video-o3-pro-video-to-video-edit",
  "videos": [
    {
      "b64_json": "<base64-encoded mp4 bytes>"
    }
  ]
}

​
Using with /ai/queue

Recommended for video editing. Returns immediately, processes in the background.

​
Enqueue

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/queue",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "kling-video-o3-pro-video-to-video-edit",
        "prompt": "Change the background to a sunset beach",
        "input_video": "https://example.com/my-video.mp4",
        "num_generations": 2,
    },
)

generations = response.json()["generations"]
for g in generations:
    print(f"ID: {g['generation_id']}, Status: {g['status']}")

​
Poll

import requests
import time

generation_id = "4ef840a4-..."
while True:
    data = requests.get(
        f"https://hub.oxen.ai/api/ai/queue/{generation_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    ).json()
    if data["status"] in {"succeeded", "failed", "cancelled"}:
        break
    time.sleep(10)

if data["status"] == "succeeded":
    print(f"Result: {data['result_url']}")
else:
    print(f"Generation {data['status']}: {data.get('error_message')}")
A generation is done when its status is succeeded, failed, or cancelled. On success, result_url points to the output file.

​
Cancel

import requests

generation_id = "4ef840a4-..."
response = requests.delete(
    f"https://hub.oxen.ai/api/ai/queue/{generation_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

print(response.json())

​
Errors

ErrorCauseFix
Field requiredMissing prompt or input_videoBoth are required
Invalid URLMalformed input_video URLProvide a valid video URL
num_generations must be an integer between 1 and 4Invalid count (via /ai/queue)Use 1–4

​
Other Kling Models

ModelInputUse CaseCost/sec
kling-video-v2-6-pro-text-to-videoText onlySimple text-to-video$0.070
kling-video-v2-6-pro-image-to-videoImageAnimate a single image$0.070
kling-video-o3-pro-image-to-videoImage + textHigher quality image animation$0.224
kling-video-o3-pro-reference-to-videoImages + textReference-conditioned, multi-shot$0.224
kling-video-o3-pro-video-to-video-editVideo + textEdit existing video$0.336
kling-video-v3-pro-motion-controlText + image + videoCamera/motion control$0.168
The O3 Pro models produce higher quality output than v2.x but cost roughly 3x more per second.