Python guide

Image to video AI API with Python

Create an async job from one image, track it safely, and download the finished video.

Python: create, poll, download
import os
import time
import requests

base_url = "https://sora2-api.com"
headers = {
    "Authorization": f"Bearer {os.environ['TIKDEK_API_KEY']}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"{base_url}/api/v1/video/sora-video",
    headers=headers,
    json={
        "model": "sora-2-pro",
        "prompt": "Slow camera push-in, rain moving across the frame",
        "url": "https://example.com/reference-frame.jpg",
        "aspectRatio": "16:9",
        "webHook": "-1",
        "isPublic": False,
    },
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["id"]

for _ in range(90):
    response = requests.post(
        f"{base_url}/api/video-generations/check-result",
        headers=headers,
        json={"taskId": task_id},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "succeeded":
        video = requests.get(task["result_url"], timeout=120)
        video.raise_for_status()
        open("result.mp4", "wb").write(video.content)
        break

    if task["status"] == "failed":
        raise RuntimeError(task.get("error_message") or "Generation failed")

    time.sleep(4)
else:
    raise TimeoutError(f"Task {task_id} did not finish in time")

A complete Python request cycle

The example uses the live Tikdek endpoints and handles every terminal task state.

Sora 2 + Stable + Pro

Pick the model string that matches your quality and cost needs: sora-2, sora-2-stable, or sora-2-pro.

Predictable polling

Create a task, then poll the check-result endpoint to keep status and progress in sync without SSE.

20 concurrent requests

Process up to 20 video generation tasks simultaneously. Contact us for higher limits.

Recommended integration flow

Keep the integration production-safe

Store API keys on the server, use bounded retries, log task IDs, and persist result files promptly.

Create the task

Send the Tikdek API request with your prompt, then store the returned taskId.

Track progress

Call the check-result endpoint until the status becomes succeeded or failed.

Deliver the video

Use the storage-backed URLs in result_url/result_urls to serve or download the generated video.

Frequently asked questions

How do I authenticate my requests?

Create an API key in the console, then include it as Authorization: Bearer YOUR_API_KEY. Keys can be rotated at any time.

How should I poll for results?

After calling create, store the taskId. Call /api/video-generations/check-result every 3-5 seconds until status is succeeded or failed, then use result_url/result_urls.

How are credits handled for failures?

We automatically refund credits when a task fails and return refund_trans_no plus credits_refunded=true in the check-result payload for audit trails.

Move from a script to production

Create an API key, run the sample, then add a webhook when your workload grows.