Blog
AI Image & Video API Guides
Hands-on model tests, production tutorials, prompt techniques, and current API pricing for generative media teams.
When a hiapi /v1/tasks Job Hangs or Times Out: Diagnosis and Retry
Tasks that sit in `pending` or hit `timeout` almost always trace back to four causes: queue backlog, an underlying model failure, oversized inputs, or an unreachable callback URL. Diagnose by polling `GET /v1/tasks/{id}` and reading `status` + `error.code` before you retry anything. Retry with exponential backoff (e.g. 5s → 15s → 45s, max 3 tries) and always create a **new** task — never POST the same idempotency body twice without a key. If a task stays in `pending` for over 90 seconds with no `error`, it's almost always a queue backlog — back off, don't hammer. For callback delivery issues, verify the URL is publicly reachable and returns 2xx within 10s; the hiapi platform does not retry indefinitely.
HappyHorse 1.1 Text-to-Video API via HiAPI: a working curl + Python tutorial
Call Alibaba's HappyHorse 1.1 text-to-video model through HiAPI's unified /v1/tasks endpoint with a working curl request, a Python polling client, and a production-ready callback pattern. The exact input schema (prompt, resolution, aspect_ratio, duration) plus the two non-obvious 400s — audio and seed are not accepted — are spelled out so the first request actually goes through.
HappyHorse 1.1 reference-to-video API: a working curl + Python tutorial
HappyHorse 1.1 R2V turns 1-9 reference images plus a text prompt into a short video over the unified async task endpoint on HiAPI. Point at each reference image inside the prompt as [Image 1], [Image 2] ... so the model knows which face, costume or setting comes from where. Resolution is 720p or 1080p, aspect_ratio is one of 9 fixed values, duration is an integer 3-15 seconds; everything else is rejected. Switch from GET polling to callback.url + callback.when="final" once you ship, and dedupe terminal events by taskId. Catch 401 permission_denied (bad key), 400 INVALID_REQUEST (the message names the bad field), and task-level status="fail" with error.code/error.message.
Happyhorse 1.1 text-to-video API: a working curl and Python tutorial
happyhorse-1.1/text-to-video is served on the unified async /v1/tasks endpoint — submit, get a taskId, then poll or receive a callback. The only required input field is `prompt`. Optional: `aspect_ratio` (9 ratios), `resolution` (720p|1080p), `duration` (3–15 seconds). Fields that look obvious but are rejected today: `size`, `audio`, `seed`, `negative_prompt` — the schema is strict, not loose. Pricing is per second of generated video, so `duration` is the cost lever; `resolution` is not. Use `callback.when="final"` in production to skip polling; only `final` is supported. Keep polling as a fallback sweeper for missed callbacks.
hiapi 'model not available' / 'model not found' errors: causes and fixes
A rejected /v1/tasks request can come from an unavailable model name, an invalid input field, a route mismatch, or a separate authentication problem. HiAPI model names do not share one naming pattern; copy the exact fixed value from the current model documentation. GPT Image 2 text-to-image requests use gpt-image-2/text-to-image, including the modality suffix. A minimal POST /v1/tasks request confirms whether the model and input shape are accepted before you add polling or callbacks. Treat 400 request validation separately from 401 invalid-key and 403 permission errors.
Why your hiapi task callback isn't firing, and how to fix it
If your task reached a terminal status but your endpoint never got a POST, the problem is almost always in the delivery path — not in hiapi. The big 5 causes: unreachable URL, TLS chain issues, your handler returning slow/non-2xx, missing Webhook Sign Key vs. strict verification, and forgetting to include the callback object at submission. Test the callback URL from outside your network first; it must accept an HTTPS POST and return 2xx within the timeout. Generate a Webhook Sign Key under /en/dashboard/settings and align your verification — don't sign with one key and verify with another. Always pair callbacks with polling GET /v1/tasks/{taskId} as the source of truth; the callback is a notification, the GET is the contract.
Runway ML Text-to-Video API in Python: A Working Example and Migrating to hiapi
The async task shape (POST → poll → download output URL) is identical across Runway-style providers and hiapi — write the loop once. Migrating Runway Gen-3 Python code to hiapi wan2.7-video/text-to-video@pro is a two-line change: API_BASE and model id. Use callbacks (callback.url + when:'final') in web apps; polling stays simpler for scripts and cron jobs. output[].url is signed and short-lived — download bytes immediately and serve from your own storage.
OpenAI API Proxy in Python: How to Build One (and When to Use HiAPI Instead)
An OpenAI API proxy is a thin server you put between your app and the model provider — it adds auth, rate limits, logging, and key rotation in one place, so your client code stays clean. A minimal FastAPI proxy is ~60 lines: validate a per-tenant key, forward the request to the upstream, stream the response back. Async (`httpx.AsyncClient`) lets one worker handle thousands of in-flight requests. The catch: this only proxies OpenAI. Add Google Veo, Qwen Image, Seedance, or any non-OpenAI model and you are now rewriting your proxy per provider. When you need many providers behind one endpoint, swap your custom proxy for HiAPI — one Bearer key, one `POST /v1/tasks`, and the provider routing is on our side.
How to Fix HiAPI Rate Limit (429) Errors
HiAPI returns HTTP 429 when a single API key sends too many concurrent or back-to-back requests to /v1/tasks or the polling endpoint. The most common trigger is fan-out: many parallel task creations from one key, or a tight polling loop on GET /v1/tasks/{taskId}. Fix it by adding exponential backoff (1s/2s/4s, cap 30s), capping client concurrency, switching from polling to callback.url, and slowing polling cadence to 2-5s with jitter. Check current usage at the HiAPI dashboard to confirm whether you are hitting account-level concurrency limits or running out of plan headroom. Use a Nano-Banana curl request to verify your key and network path once the retry layer is in place.
Z-Image API: Pricing, API Key, Examples, and When to Use It
Z-Image is Alibaba's Tongyi Z-Image, a fast, efficient photorealistic text-to-image model that also renders accurate in-image text in both English and Chinese. On HiAPI the callable model id is plain z-image. There is no separate z-image-turbo id to call, so don't code against one. Calls go through the unified async task API, POST /v1/tasks then poll until the image URL is ready. The input takes prompt plus aspect_ratio (and optional resolution). A size or width times height field is rejected, so leave it out. It's a low-cost, pay-as-you-go option. See live pricing rather than any number you read in a blog post.
Build with the models you just read about.
Compare image, video, and audio models, then use the same API workflow in production.