Video webhooks
Have the end of a video job posted to your server, instead of asking for it.
- Put up a receiver on a public HTTPS address.
- Send the job with that address in
callback_url. - Read the post.
- Fetch the clip.
1. Put up a receiver
When a job ends, OpenDunes sends a POST with a JSON body to the address you gave. The receiver below answers 200 at once, drops a post it has already seen, and prints the job's end. It listens on port 8080: put it behind your app's HTTPS address.
import json
from http.server import BaseHTTPRequestHandler, HTTPServer
PORT = 8080
seen = set()
class Receiver(BaseHTTPRequestHandler):
def do_POST(self):
length = int(self.headers["Content-Length"])
event = json.loads(self.rfile.read(length))
key = self.headers["X-OpenDunes-Idempotency-Key"]
self.send_response(200)
self.end_headers()
if key in seen:
return
seen.add(key)
job = event["data"]
if event["type"] == "video.generation.completed":
print(job["id"], "completed", job["usage"]["cost"], "DA")
else:
print(job["id"], job["status"], job.get("error"))
HTTPServer(("", PORT), Receiver).serve_forever()Do slow work before you answer. A post that gets no 2xx is sent again, and your work runs twice.
Answer 2xx first, then work. Drop a post whose X-OpenDunes-Idempotency-Key you have already handled.
The receiver keeps the keys it has seen in memory, lost at each restart. In your app, keep them where your jobs are kept.
2. Send the job with that address
Add callback_url to the job: your receiver's public HTTPS address. The samples read it from the environment variable VIDEO_CALLBACK_URL, for example https://your-app.dz/hooks/video. The rest of the job is as in Text to video.
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/videos"
MODEL = "alibaba/wan-3.0"
PROMPT = "Fishing boats leave the port of Béjaïa at dawn, wide shot"
CALLBACK_URL = os.environ["VIDEO_CALLBACK_URL"]
request = urllib.request.Request(
ADDRESS,
data=json.dumps(
{
"model": MODEL,
"prompt": PROMPT,
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
"callback_url": CALLBACK_URL,
}
).encode(),
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
job = json.load(response)
print(job["id"], job["status"])The answer is 202, with the job's id and status pending: keep the id. An address that is not HTTPS on the public internet gets a 400, and no job is made. Every field: Clips.
Asking still works beside a callback_url. If your receiver was down when the job ended, GET /v1/videos/{id} still answers how it ended, free.
3. Read the post
One post per job, when it ends. The type names the end.
type | The job |
|---|---|
video.generation.completed | made the clip |
video.generation.failed | failed; data.error holds the provider's reason |
video.generation.cancelled | was cancelled |
video.generation.expired | lapsed before a clip was made |
| Field | Holds |
|---|---|
type | the end, from the table above |
created_at | when the post was sent |
data | the job as the last ask would answer it, with its model |
A completed post, illustrative:
{
"type": "video.generation.completed",
"created_at": "2026-09-29T09:20:11Z",
"data": {
"id": "3f2b8c1e-6a4d-4e9b-9c7a-2d5e8f1a0b64",
"status": "completed",
"model": "alibaba/wan-3.0",
"unsigned_urls": [
"https://opendunes.com/v1/videos/3f2b8c1e-…/content?index=0"
],
"usage": {
"cost": 42.5,
"is_byok": false
}
}
}Each post carries X-OpenDunes-Idempotency-Key: the job id and the status, joined by -, the same on every repeat of one post.
A post can arrive twice. Answer any 2xx; a post that gets none is sent again, up to six times in all. Handle a key once.
4. Fetch the clip
On video.generation.completed, fetch the clip with the job id and your API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →: GET /v1/videos/{id}/content?index=0. The answer is the MP4's bytes, free to fetch as often as you like. Text to video saves one in its last lines.
The charge was taken once, at completed, and data.usage.cost carries it in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →. A job that ends any other way charges nothing.
Last modified on