A 10-second 1080p reference-to-video render almost never finishes inside a standard 30-second HTTP timeout. When an application backend holds a reverse-proxy socket open while upstream GPU workers decode reference clips and synthesize hundreds of frames, Nginx or Cloudflare drops the connection and hands the caller a 504 gateway timeout.
Blindly retrying that failed request creates a worse failure: the original job may already sit in the render queue, so a second POST spawns a duplicate video and charges the credit wallet twice. Splitting job submission from result delivery fixes both failure modes when you pair local media pre-uploads, a deterministic Idempotency-Key, 480p draft or beat-planned prompt validation, and signed HMAC webhooks backed by cursor polling.
The engineering patterns below map directly to the async task contract on HotAPI and its API getting started guide. Every snippet and table uses the live schemas for Seedance 2.5 Spicy (seedance-2.5-spicy), Berry 1.0 Pro Spicy (berry-1.0-pro-spicy), and Wan 3.0 (w3.0-spicy and w3.0-pro-spicy).
What happens when a client retries a timed-out video POST without an idempotency key?
Retrying a video POST without an Idempotency-Key header creates a second independent task and deducts credits again whenever the first request already crossed the API gateway boundary.
Every generation call on POST /v1/<model> or the unified POST /v1/tasks route returns 202 Accepted immediately with status: "queued", estimated_credits_cost, and the task id. Passing an Idempotency-Key header tied to your internal job ID turns network retries into safe replays: sending the same key with an identical JSON body returns 200 OK with the existing task object instead of queuing a duplicate render, while sending the same key with a modified payload returns 409 conflict_error (idempotency_key_reused) so silent parameter drift fails loudly.
If a user cancels a queued render before rendering begins, DELETE /v1/tasks/{id} refunds estimated_credits_cost in full only when started_at is still null. Once a worker picks up the job, the charge stands. Failed tasks refund automatically, and your submission client should still respect 429 (rate_limit_error) and 503 (service_unavailable) Retry-After headers before sleeping, as detailed in the HotAPI async tasks guide and the model catalog.
import crypto from "node:crypto"; interface VideoJobRequest { jobId: string; referenceImageUrls: string[]; prompt: string; durationSeconds: number; webhookUrl: string; } export async function submitSeedanceReferenceJob(job: VideoJobRequest) { const endpoint = new URL( "https://api.hotapi.ai/v1/seedance-2.5-spicy/reference-to-video", ); endpoint.searchParams.set("webhook", job.webhookUrl); const payload = JSON.stringify({ reference_image_urls: job.referenceImageUrls, prompt: job.prompt, duration_seconds: job.durationSeconds, resolution: "480p", draft: true, generate_audio: false, }); // Derive a stable key from the internal job id so network retries replay cleanly. const idempotencyKey = `vid_${crypto .createHash("sha256") .update(job.jobId) .digest("hex") .slice(0, 24)}`; for (let attempt = 0; attempt < 3; attempt += 1) { const res = await fetch(endpoint, { method: "POST", headers: { Authorization: `Bearer ${process.env.HOTAPI_KEY}`, "Idempotency-Key": idempotencyKey, "Content-Type": "application/json", }, body: payload, signal: AbortSignal.timeout(15_000), }); if (res.status === 202 || res.status === 200) { return (await res.json()) as { id: string; status: string; estimated_credits_cost: number; }; } if (res.status === 429 || res.status === 503) { const retryAfterSec = Number(res.headers.get("retry-after") ?? "5"); await new Promise((r) => setTimeout(r, retryAfterSec * 1000)); continue; } const err = await res.json(); throw new Error( `HotAPI submission failed (${res.status}) [${err?.error?.request_id}]: ${err?.error?.message}`, ); } throw new Error("Exhausted retry budget submitting reference-to-video task"); } How do Seedance 2.5, Berry 1.0 Pro, and Wan 3.0 differ on reference limits and billing?
Seedance 2.5, Berry 1.0 Pro, and Wan 3.0 accept different ceilings for image, audio, video, and document inputs, and every reference-to-video endpoint bills input video seconds on top of output video seconds.
Using 1,000 credits = $1.00 USD, reference images, reference audio, and document or web links add zero billable seconds. Any URL in reference_video_urls, by contrast, has its duration probed at submission time and billed alongside duration_seconds at the selected resolution tier: sending a 10-second reference video for a 5-second output bills 15 seconds total. Unreadable files or clips outside each model's duration bounds are rejected at submission before any credits leave the balance.
| Model endpoint | Image refs | Audio refs | Video refs | Resolution tiers (credits/s) | Duration & min | Notable request controls |
|---|---|---|---|---|---|---|
POST /v1/seedance-2.5-spicy/reference-to-video | 1-30 (300-6000px per side) | 1-10 (audio-only supported) | 1-10 (<= 30s total) | 480p: 205.6, 720p: 462.4, 1080p: 1,137.2 | 4-30s (min 823 cr) | draft: true, `output_format: "mp4" \ |
{% raw %}POST /v1/berry-1.0-pro-spicy/reference-to-video | 1-10 (HTTP/HTTPS or base64) | 1-5 (audio-only supported) | 1-5 (1-15s each, <= 15s total, <= 100MB) | 1080p: 270, 2k: 300, 4k: 345 | 2-30s (min 540 cr) | resolution required, prompt_extend, seed |
POST /v1/w3.0-spicy/reference-to-video | 1-10 (HTTP/HTTPS or base64) | 1-5 (audio-only supported) | 1-5 (1-15s each, <= 15s total, <= 100MB) | 480p: 75, 720p: 150, 1080p: 300 | 2-30s (min 150 cr) | file_url or link_url (mutually exclusive), prompt_extend |
POST /v1/w3.0-pro-spicy/reference-to-video | 1-10 (HTTP/HTTPS or base64) | 1-5 (audio-only supported) | 1-5 (1-15s each, <= 15s total, <= 100MB) | 1080p: 270, 2k: 300, 4k: 345 | 2-30s (min 540 cr) | file_url or link_url (mutually exclusive), prompt_extend |
Two behavior flags trip production workers most often. First, on Seedance 2.5 Spicy reference-to-video, generate_audio defaults to true, and the upstream provider runs moderation on generated audio tracks after synthesis; for spicy visual scenes, an audio rejection fails the whole task and refunds credits without returning video, so pass generate_audio: false whenever you supply your own audio or want silent output. Second, Wan 3.0 Spicy and Wan 3.0 Pro Spicy pin prompt_extend on when you pass file_url (up to 100MB and 50 pages) or link_url, whereas Berry 1.0 Pro Spicy skips document inputs and focuses on multi-media references up to 4K. For deeper trade-offs across tiers, see the Seedance 2.5 vs Wan 3.0 comparison, browse the full model comparisons index, or check every active endpoint in model reference docs.
Why do reference image dimensions and upload TTLs break video tasks before rendering starts?
Reference-to-video requests fail early if you pass unuploaded local files, images outside per-side pixel rules, or expired temporary upload URLs past their 24-hour TTL.
On Seedance 2.5, every image in reference_image_urls must stay between 300px and 6000px on each side. On Wan 3.0 and Berry 1.0 Pro, passing clips shorter than 1 second or larger than 100MB triggers validation failures, and POST /v1/uploads rejects files whose sniffed magic bytes fail JPEG/PNG/WebP (10 MB max, 8192px max side) or MP4/MOV/WebM/audio (25 MB max) checks. Because POST /v1/uploads URLs expire 24 hours after upload, never cache them as permanent character sheets across multi-day campaigns; upload right before submitting or store permanent anchor assets in your own object storage.
When reference media includes human faces, HotAPI automatically registers trusted faces when an upstream video model requires it, capped at 200 distinct faces per organization. If a multi-tenant workspace hits 400 trusted_face_limit_reached, prune stale entries via GET /v1/face-assets and DELETE /v1/face-assets/{id}, as covered in the HotAPI uploads documentation and the character-consistent video pipeline playbook.
# 1. Upload a local character reference image (24h URL TTL) UPLOAD_URL=$(curl -sS -X POST https://api.hotapi.ai/v1/uploads \ -H "Authorization: Bearer $HOTAPI_KEY" \ -F "file=@./character-sheet.jpg" | jq -r '.url') # 2. Reference the uploaded image by index in a Wan 3.0 Pro 1080p render curl -sS -X POST "https://api.hotapi.ai/v1/w3.0-pro-spicy/reference-to-video?webhook=https://app.example.com/hooks/hotapi" \ -H "Authorization: Bearer $HOTAPI_KEY" \ -H "Idempotency-Key: shot_04_take_1" \ -H "Content-Type: application/json" \ -d "{ \"reference_image_urls\": [\"$UPLOAD_URL\"], \"prompt\": \"[Slow dolly in] Image 1 walks across a rain-slicked neon crosswalk, warm amber reflection on asphalt, steady 35mm lens.\", \"duration_seconds\": 6, \"resolution\": \"1080p\", \"ratio\": \"16:9\", \"generate_audio\": false }" How does beat-planned prompt timing prevent subject morphing across 8-to-30-second clips?
Breaking an 8-to-30-second clip into timestamped 2.5-to-5-second action beats prevents the diffusion backbone from collapsing three unrelated movements into limb distortion or abrupt camera whips.
Packing four actions into a 6-second prompt forces rapid pose interpolation between frames. Instead, anchor camera movement and lighting in a bracketed opening clause like [Static medium shot] or [Slow tracking shot], divide the clip into explicit windows (Beat 1 (0-4s) and Beat 2 (4-8s)), and place sound direction at the tail when generate_audio is enabled. On Wan 3.0, address inputs explicitly per type (Image 1, Video 1) so the model binds motion and appearance to the right asset. You can test beat spacing and credit totals before coding with the video prompt beat planner.
On seedance-2.5-spicy, pair beat-planned timing with a two-stage draft flow. Submitting with draft: true and resolution: "480p" (or omitting resolution, which defaults to 480p; any higher resolution is rejected with draft: true) lets you inspect pacing and framing at 205.6 credits/s instead of 1,137.2 credits/s. A 480p draft is not discounted, so its savings come purely from catching broken framing before committing to 1080p. Once a draft succeeds, pass its task ID to POST /v1/seedance-2.5-spicy/draft-to-video within 7 days; the final reuses the draft's prompt, references, duration, ratio, seed, and audio flags verbatim, and allows switching output_format to "mov" for post-production grading as documented in the Seedance 2.5 draft-to-video spec.
# Promote a succeeded 480p draft task into a 1080p 10-bit HEVC MOV final curl -sS -X POST "https://api.hotapi.ai/v1/seedance-2.5-spicy/draft-to-video?webhook=https://app.example.com/hooks/hotapi" \ -H "Authorization: Bearer $HOTAPI_KEY" \ -H "Idempotency-Key: finalize_task_8sd9f7aQ2" \ -H "Content-Type: application/json" \ -d '{ "draft_task_id": "task_8sd9f7aQ2", "output_format": "mov" }' When should a worker rely on HMAC webhooks instead of polling GET /v1/tasks/{id}?
Any generation job taking longer than 10 seconds should use ?webhook= push callbacks as the primary completion path, paired with a 60-second background sweeper calling GET /v1/tasks?status=active&fields=summary or GET /v1/tasks/{id} as a fallback.
HotAPI splits rate limits across two independent 60-second sliding windows: 60 requests/minute by default for generation submissions and 600 requests/minute (10x base RPM) for GET /v1/tasks and GET /v1/tasks/{id} reads. Polling a few active jobs at a 5-second interval will not eat into submission capacity, yet scaling to hundreds of concurrent renders wastes worker cycles if each job opens its own polling loop. Passing ?webhook=https://... triggers a signed POST on task.succeeded, task.failed, or task.cancelled and retries non-2xx responses up to five additional times (+1m, +5m, +30m, +2h, +12h).
Four webhook handler checks prevent silent production bugs. Read the raw HTTP body bytes before any JSON parser reformats whitespace, reject timestamps older than 300 seconds, compare the v1 HMAC-SHA256 hex digest of <timestamp>.<raw_body> in constant time against your org-wide HOTAPI_WEBHOOK_SECRET, and deduplicate deliveries on HotAPI-Event-Id (or id in the signed body). Always reply with a 2xx status within 10 seconds and copy output.assets[].url into durable storage before expires_at.
Full signature headers live in the HotAPI webhooks guide. For queue worker code, refer to the FastAPI webhook integration blueprint inside the integrations hub, along with the async webhook worker queue playbook in the engineering playbooks index.
import hashlib import hmac import json import os import time from fastapi import FastAPI, Header, HTTPException, Request app = FastAPI() WEBHOOK_SECRET = os.environ["HOTAPI_WEBHOOK_SECRET"] PROCESSED_EVENTS: set[str] = set() # Replace with an atomic DB unique constraint in prod. @app.post("/hooks/hotapi") async def receive_task_webhook( request: Request, hotapi_signature: str = Header(default=""), hotapi_event_id: str = Header(default=""), ): raw_body = await request.body() parts = dict( item.split("=", 1) for item in hotapi_signature.split(",") if "=" in item ) t_str, v1 = parts.get("t"), parts.get("v1") if not t_str or not v1: raise HTTPException(status_code=400, detail="Malformed HotAPI-Signature header") try: timestamp = int(t_str) except ValueError as exc: raise HTTPException(status_code=400, detail="Invalid timestamp") from exc if abs(int(time.time()) - timestamp) > 300: raise HTTPException(status_code=401, detail="Stale webhook timestamp") signed_payload = f"{t_str}.".encode("utf-8") + raw_body expected_v1 = hmac.new( WEBHOOK_SECRET.encode("utf-8"), signed_payload, hashlib.sha256, ).hexdigest() if not hmac.compare_digest(v1, expected_v1): raise HTTPException(status_code=401, detail="Signature mismatch") envelope = json.loads(raw_body) dedupe_key = envelope.get("id") or hotapi_event_id if dedupe_key in PROCESSED_EVENTS: return {"ok": True, "deduped": True} PROCESSED_EVENTS.add(dedupe_key) task = envelope["data"] if task["status"] == "succeeded": asset_urls = [asset["url"] for asset in task.get("output", {}).get("assets", [])] # Enqueue durable copy to your own S3/R2 bucket before task["expires_at"]. print(f"Task {task['id']} succeeded with {len(asset_urls)} asset(s)") elif task["status"] in ("failed", "cancelled"): print(f"Task {task['id']} ended: {task.get('error')}") return {"ok": True} How should production teams sequence a reference-to-video rollout?
Start on a dedicated development organization with 480p w3.0-spicy or draft: true Seedance 2.5 submissions, verify HMAC raw-body checks against a public HTTPS tunnel, and promote only after your worker survives duplicate webhook deliveries and 429 backoffs.
Keep submission requests strictly server-side so HOTAPI_KEY never enters client bundles, run a 60-second sweeper over non-terminal rows older than 90 seconds, and benchmark side-by-side quality between Seedance 2.5 Spicy and Wan 3.0 Spicy on identical reference sets before locking your default production tier.

