Image and video generation: the Jobs API

TL;DR — POST /v2/jobs with a model, a style and your inputs returns a job_id in about a second. Wandura generates in the background and POSTs the signed final job to your webhook_url; GET /v2/jobs/{job_id} is the fallback. Test keys (wdr_test_…) are a free sandbox. A bad body is refused at once with 422 and the reason; a job that fails, times out, is cancelled or is blocked by moderation is not charged. This is the recommended way in for every new integration.

Basics#

• Base URL: https://api.wandura.ai (region Singapore).
• OpenAPI 3.1: api.wandura.ai/v2/openapi.json, no key needed. The Jobs API is the operations tagged Jobs.
• Flow: submit with webhook_url and an Idempotency-Key → 202 {job_id, status: "queued"} → Wandura POSTs the signed final job to webhook_url and you answer 200 → if the webhook never arrives, poll GET /v2/jobs/{job_id} → download output[0].url.
• Every request is JSON over HTTPS.

Authentication and keys#

Every call sends Authorization: Bearer <key>. Create keys in the console; a product can have several and rotate them. Keep keys on your server.

A job belongs to the product of the key that submitted it: another product's key gets 404 for it.

Models and the schema#

Two models, one per output kind.

The v1 in a model id is the model version, not the API version. Ids are fixed: a breaking change gets a new id (…-v2), never a silent change. Styles are added and retired under a model without changing it.

curl https://api.wandura.ai/v2/models -H "Authorization: Bearer $WANDURA_KEY"

# JSON Schema (2020-12) of the submit body for one model: types, required fields, min/max,
# lengths, the list of style ids, and per style which fields it requires and which it does not take
curl https://api.wandura.ai/v2/models/wandura-video-v1/schema -H "Authorization: Bearer $WANDURA_KEY"

Read the schema at build time or on a schedule to build your input forms; it changes when styles are added or retired.

Styles#

A style is a packaged look: its prompt, its generation steps and its settings stay on Wandura's side. GET /v2/styles?model=wandura-video-v1 lists the live styles your key can run:

{
  "id": "sty_motion_clip_test", "object": "style", "model": "wandura-video-v1", "name": "Motion Clip",
  "description": "Bring a still image to life with gentle camera motion.",
  "input_hint": "One clear image of the subject you want to bring to life.",
  "preview_url": "https://<wandura-storage-host>/samples/v1/motion-clip.mp4",
  "inputs": { "image_url": "required", "prompt": "optional" },
  "max_job_seconds": 300, "price": { "credits": 23.4, "usd": 0.234 }
}

Submit, poll, cancel#

curl -X POST https://api.wandura.ai/v2/jobs \
  -H "Authorization: Bearer $WANDURA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-job-123" \
  -d '{
    "model": "wandura-video-v1",
    "style": "sty_motion_clip_test",
    "image_url": "https://your-bucket.example.com/u/42/photo.jpg?X-Amz-Signature=...",
    "prompt": "a girl smiling at the camera",
    "webhook_url": "https://your-backend.example.com/hooks/wandura",
    "end_user_id": "user_42"
  }'
# HTTP 202
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 59
# X-RateLimit-Reset: 1791897360
# X-Concurrency-Limit: 20
# X-Concurrency-Running: 3
# X-Concurrency-Waiting: 0
# {"job_id":"run_QVqsXwr7VGSP","status":"queued","model":"wandura-video-v1","created_at":"2026-10-13T13:15:40.825Z"}

curl https://api.wandura.ai/v2/jobs/run_QVqsXwr7VGSP -H "Authorization: Bearer $WANDURA_KEY"

curl -X POST https://api.wandura.ai/v2/jobs/run_QVqsXwr7VGSP/cancel -H "Authorization: Bearer $WANDURA_KEY"

• Input URLs are downloaded when the job starts, not when you submit. A URL that cannot be downloaded ends the job failed, not charged. Keep a presigned URL valid for at least the style's max_job_seconds plus 10 minutes.
• Cancel works while the job is queued: 200, status cancelled, not charged, and the webhook fires. Once the job is processing it runs to the end, and cancel answers 409 JOB_NOT_CANCELLABLE.

Relax lane and a style's own inputs#

Rolling out. Two optional fields of POST /v2/jobs, so every style a key can run also runs as a job. A body without them is answered exactly as before.

lane: priority (default) or relax.

The job body is the same for both lanes (it has no lane field). Both prices are in the public catalog (GET /v2/public/styles, price.priority and price.relax).

inputs: an object of the style's own inputs that no field of the table above carries, named as in the style's input schema. Examples: a keep_audio switch, a second text field (prompt fills the first), a mask_url, or a video_url on an image style.

curl -X POST https://api.wandura.ai/v2/jobs \
  -H "Authorization: Bearer $WANDURA_KEY" -H "Content-Type: application/json" \
  -d '{"model": "wandura-video-v1", "style": "<style id>", "image_urls": ["https://…/photo.jpg"], "lane": "relax", "inputs": {"keep_audio": false}}'

• Where to find a style's inputs: GET /v2/public/styles/{style} → inputs (no key). Each style's OpenAPI, GET /v2/public/styles/{style}/openapi.json, carries the exact POST /v2/jobs body for that style, with an example.
• An input that a field above carries goes in that field, not in inputs: {"field": "inputs.image_urls", "reason": "send it as image_urls"}.
• A style whose required input is not one of the fields above runs only when the body sends inputs. It is not listed in GET /v2/styles or the model schema; without inputs it gets the same 422 as an unknown style.
• GET /v2/models/{model_id}/schema lists only the fields of the table above; lane and inputs are in the OpenAPI (JobRequest).
• Audio styles are not on the Jobs API yet.

Problems with these fields come back as 422 INVALID_INPUT details, like every other field:

Validation is strict and synchronous#

A wrong body never becomes a job. Wandura checks the whole body at submit and lists every problem:

HTTP 422
{"error":{"code":"INVALID_INPUT","message":"Validation failed.","retryable":false,"details":[
  {"field":"num_outputs","reason":"must be 1 (one output per job)"},
  {"field":"aspect_ratio","reason":"style sty_motion_clip_test does not take this field"},
  {"field":"image_url","reason":"required by style sty_motion_clip_test"}]}}

• Styles fix their own aspect ratio, resolution and duration. Today's styles do not take aspect_ratio, resolution, duration or seed, so sending one returns 422 with the reason. Send only what the style's inputs lists, and use the model schema to know which.
• An unknown field, a missing required field, a malformed URL and an unknown style are all 422.

Idempotency#

Send an Idempotency-Key (1 to 255 characters) on every submit so a retry never runs twice.

• Same key and same body: the same job (200, header Idempotent-Replayed: true, the job's current status).
• Same key and another body: 409 IDEMPOTENCY_KEY_REUSED. Use a new key for a new job.
• No header: Wandura derives a key from your API key and the body, so the same body within 10 minutes is the same job.

Statuses#

queued → processing → succeeded | failed | cancelled | timeout

The last four are final and never change again.

Errors inside a finished job (error.code):

A moderation block is a normal final job, not an HTTP error:

{"job_id":"run_4kT9wQx2LmPa","status":"failed","model":"wandura-video-v1","style":"sty_motion_clip_test","output":null,
 "error":{"code":"CONTENT_MODERATION_BLOCKED","message":"The input or the result was blocked by content moderation. Not charged.","retryable":false},
 "created_at":"2026-10-13T13:12:02.410Z","completed_at":"2026-10-13T13:12:03.902Z"}

Output#

output is a list with one file, and null until the job succeeded.

{"job_id":"run_…","status":"succeeded","model":"wandura-image-v1","style":"sty_…",
 "output":[{"url":"https://<wandura-storage-host>/outputs/2026-10-10/<random name>.png","type":"image/png",
   "width":48,"height":32,"duration":null,"fps":null,"size_bytes":136,"seed":null,"expires_at":"2026-10-13T00:00:00.000Z"}],
 "error":null,"created_at":"2026-10-10T00:00:00.000Z","completed_at":"2026-10-10T00:00:00.000Z"}

• url is an HTTPS link on Wandura storage (the Wandura CDN), downloadable directly with a plain GET. It is not a link to any third party.
• Works for at least 7 days. expires_at says until when the link is guaranteed. Copy the file to your own storage before then if you need it longer.
• Metadata is read from the file: type, width, height, duration and fps (video), size_bytes, seed. A value that cannot be read is null.
• Test-key samples carry null metadata and do not expire.
• The job record itself is kept well past 7 days: GET /v2/jobs/{job_id} keeps answering for old jobs.

Webhooks#

Each job with a webhook_url gets one POST when it reaches a final status (no intermediate webhooks). The body is exactly what GET /v2/jobs/{job_id} returns at that moment.

1. Have a signing secret once: in the console, either save a Webhook endpoint URL (its signing secret then signs job webhooks too), or create a dedicated "Jobs API signing secret" (Create; it is shown once; Roll replaces it at once). When the product has a Jobs API signing secret, that one signs job webhooks. Until it has one of the two, a submit with webhook_url is refused with 422.
2. Verify every request on the raw body: X-Signature is the hex HMAC-SHA256 of X-Timestamp + "." + raw body with your secret, and X-Timestamp (unix seconds) is within 5 minutes of now.
3. Answer 2xx within 10 seconds, then do your work. Dedupe on job_id (or the Wandura-Event-Id header, the same on every retry): delivery is at least once.

POST /hooks/wandura HTTP/1.1
Content-Type: application/json
User-Agent: Wandura-Webhooks/1
X-Timestamp: 1791897341
X-Signature: 6f1c…(64 hex characters)
Wandura-Event-Id: evt_…
Wandura-Event-Type: job.ended

{"job_id":"run_QVqsXwr7VGSP","status":"succeeded","model":"wandura-video-v1", …}

Retry policy#

A non-2xx answer (redirects included), a timeout or a network error is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 24 hours: 7 attempts over about 31 hours, with the same body and job_id. A URL whose host resolves to a private or reserved address is never called. If every attempt fails, the job is still there: poll it.

Verify the signature#

Node.js (Express):

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

// raw = the body exactly as received (before JSON.parse)
export function verifyWandura(raw, headers, secret, toleranceS = 300) {
  const ts = headers['x-timestamp'], sig = String(headers['x-signature'] || '');
  if (!/^\d+$/.test(ts || '') || Math.abs(Date.now() / 1000 - Number(ts)) > toleranceS) return false;
  const want = createHmac('sha256', secret).update(`${ts}.${raw}`).digest('hex');
  return sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

const app = express();
app.post('/hooks/wandura', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verifyWandura(raw, req.headers, process.env.WANDURA_JOBS_SECRET)) return res.sendStatus(401);
  const job = JSON.parse(raw); // { job_id, status, output, error, ... }
  // store it, dedupe on job.job_id, then:
  res.sendStatus(200);
});

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, request

def verify_wandura(raw: bytes, headers, secret: str, tolerance_s: int = 300) -> bool:
    ts, sig = headers.get("X-Timestamp", ""), headers.get("X-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance_s:
        return False
    want = hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, sig)

app = Flask(__name__)

@app.post("/hooks/wandura")
def wandura_hook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    if not verify_wandura(raw, request.headers, os.environ["WANDURA_JOBS_SECRET"]):
        return "", 401
    job = request.get_json()  # dedupe on job["job_id"]
    return "", 200

Use the sandbox to test your endpoint: a wdr_test_… job fires the same signed webhook.

Errors#

Every error answer is {"error": {"code", "message", "retryable"}}, plus details for INVALID_INPUT. Branch on code; quote the X-Request-Id header when you ask for support. Rolling out: each error also carries docs_url, a link to its section on the Errors page, and the headers Wandura-Error-Code and Wandura-Should-Retry (see Error body and headers).

A 429 always carries a Retry-After header (seconds). Wait that long, add a little random jitter, and retry with the same Idempotency-Key. Retry only the errors marked retryable. Submit answers, 429 included, also carry X-Concurrency-Limit, X-Concurrency-Running and X-Concurrency-Waiting: see Queue and congestion.

HTTP/1.1 429
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791897360

{"error":{"code":"RATE_LIMITED","message":"Too many jobs submitted this minute for this product. Retry after the Retry-After header.","retryable":true}}

Limits#

These are today's defaults, and they are raised per customer on request: tell Wandura your expected peak (jobs per minute, video share) and the limits for your product are raised.

Live status and maintenance notices: wandura.instatus.com. No uptime SLA is committed yet.

What is charged#

• Charged: a succeeded job on a live key, at the style price.
• Not charged: failed (generation error, unusable input, moderation block), timeout, cancelled, and anything refused at submit (4xx). The price is held when the job starts and released when it ends without a result.
• Test keys never charge.

Versioning#

• Paths are versioned (/v2/…). Model ids carry their own version (wandura-image-v1 is the model version, not the API version).
• A breaking change comes as a new path version or a new model id, announced at least 30 days ahead. The old one keeps working during that time.
• Additive changes can ship at any time: new styles, new optional fields, new error codes, new fields in answers. Ignore fields you do not know, and treat an unknown error.code as non-retryable unless retryable says otherwise.

Contact#

• Status and maintenance: wandura.instatus.com.
• Questions, higher limits, incidents: [Wandura integration contact: to be added].
• Send the job_id and the X-Request-Id of the call.