Hunyuan Video Fast is available on Novita AI at POST https://api.novita.ai/v3/async/hunyuan-video-fast. It is the speed-optimized variant of Tencent’s open-source Hunyuan Video foundation model — it cuts generation time compared to the standard version at the cost of some motion fidelity, making it practical for high-throughput pipelines, prompt iteration, and staging workflows where turnaround speed matters more than peak cinematic quality.
Like all Novita async video APIs, it returns a task_id on submission and delivers the video URL once the task completes. This guide covers the endpoint, request format, working Python and cURL examples, and where the fast variant fits versus the standard model.
When to Use Hunyuan Video Fast vs Standard
The fast variant is the right choice when generation turnaround and request volume matter more than peak visual quality. Standard Hunyuan Video produces higher-fidelity motion and better prompt adherence per generation. The fast variant cuts that time significantly — useful for:
- Prompt iteration — test many variations cheaply before committing to a full-quality render
- High-throughput pipelines — batch content generation where latency per clip directly affects throughput
- Staging and internal review — get shareable output quickly, then switch to standard for final delivery
- Low-latency applications — production workflows with tight response-time budgets
If output quality is the primary constraint — broadcast, final delivery, or photorealistic motion — use the standard Hunyuan Video endpoint instead.
Step 1: Get Your Novita AI API Key
Sign up at novita.ai and generate an API key from the key management page. New accounts receive free credits. Store the key as an environment variable — never hard-code it in source files.
export NOVITA_API_KEY="your_api_key_here"Step 2: Endpoint and Model ID
| Field | Value |
|---|---|
| Submit endpoint | POST https://api.novita.ai/v3/async/hunyuan-video-fast |
| Result retrieval | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| Auth header | Authorization: Bearer $NOVITA_API_KEY |
| Content-Type | application/json |
Official API reference: novita.ai/docs/api-reference/model-apis-hunyuan-video-fast
Step 3: Send Your First Request
Submit a generation request with your prompt and output settings:
curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
"negative_prompt": "blurry, low quality, distorted, watermark",
"width": 1280,
"height": 720,
"seed": -1
}'The API returns a task_id immediately:
{
"task_id": "hunyuan-fast-abc123"
}The video is not in this response — store the task_id and use it in the next step.
Step 4: Poll for the Video Result
curl -s "https://api.novita.ai/v3/async/task-result?task_id=hunyuan-fast-abc123" \
-H "Authorization: Bearer $NOVITA_API_KEY"Keep polling until task_status is TASK_STATUS_SUCCEED:
{
"task_status": "TASK_STATUS_SUCCEED",
"videos": [
{
"video_url": "https://cdn.novitai.com/output/...",
"video_url_ttl": 3600,
"video_type": "mp4"
}
]
}Download or store video_url promptly — it expires after video_url_ttl seconds.
Task Status Values
| Status | Meaning |
|---|---|
TASK_STATUS_QUEUED | Request accepted, waiting to run |
TASK_STATUS_PROCESSING | Generation in progress |
TASK_STATUS_SUCCEED | Complete — video URL available in videos[0].video_url |
TASK_STATUS_FAILED | Generation failed — check the response for a failure reason |
Python Example
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(
prompt: str,
negative_prompt: str = "",
width: int = 1280,
height: int = 720,
seed: int = -1,
) -> str:
payload = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"width": width,
"height": height,
"seed": seed,
}
resp = requests.post(
f"{BASE_URL}/v3/async/hunyuan-video-fast",
headers=HEADERS,
json=payload,
)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/v3/async/task-result",
headers=HEADERS,
params={"task_id": task_id},
)
resp.raise_for_status()
data = resp.json()
status = data.get("task_status", "")
if status == "TASK_STATUS_SUCCEED":
return data
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Task failed: {data}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
task_id = submit_video(
prompt="A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
negative_prompt="blurry, low quality, distorted, watermark",
width=1280,
height=720,
)
print(f"Task submitted: {task_id}")
result = poll_result(task_id)
for video in result.get("videos", []):
print(f"Video URL (expires in {video['video_url_ttl']}s): {video['video_url']}")cURL Example
# Step 1: Submit the generation request
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A timelapse of a city skyline transitioning from dusk to night, cinematic",
"negative_prompt": "blurry, low quality, distorted",
"width": 1280,
"height": 720,
"seed": 42
}' | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Step 2: Poll until complete
while true; do
RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.task_status')
if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
echo "$RESULT" | jq -r '.videos[0].video_url'
break
elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
echo "Failed: $RESULT"
break
fi
echo "Status: $STATUS — waiting..."
sleep 5
doneKey Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description of the video scene, subject, motion, and style |
negative_prompt | string | No | Elements to avoid in the output (e.g., “blurry, low quality”) |
width | integer | No | Output width in pixels — check the API docs for supported values |
height | integer | No | Output height in pixels — paired with width to set resolution |
seed | integer | No | Set a fixed integer to reproduce the same output; -1 for random |
For the complete parameter list including duration options, maximum resolution constraints, and any model-specific fields, see the Hunyuan Video Fast API reference.
Pricing and Limits
Verify current per-video pricing at the Novita AI models page. Video generation pricing is typically per generated clip and varies by resolution and duration. Check the pricing page before building a cost model for production workloads.
Confirm the following limits in the official docs before deploying:
- Maximum prompt character length
- Supported resolution values (width × height combinations)
- Maximum video duration in seconds
- Rate limits and concurrent task caps per API key
The fast variant typically costs less per clip than the standard model due to reduced compute time — verify the current differential on the Novita pricing page.
Troubleshooting
401 Unauthorized — The API key is missing, invalid, or expired. Confirm NOVITA_API_KEY is set and the key is active in your Novita AI dashboard.
422 Unprocessable Entity — A required parameter is missing or a value is out of range. Confirm prompt is non-empty and that width/height values are in the supported set from the API docs.
Task stays in TASK_STATUS_PROCESSING — Generation is still running. The fast variant completes faster than standard, but higher resolutions and longer durations take more time. Increase your polling timeout for large outputs.
video_url returns 403 or 404 — The URL has expired (video_url_ttl elapsed). In production, download or transfer the video immediately after TASK_STATUS_SUCCEED — do not rely on the hosted URL as permanent storage.
Consistent quality issues on specific prompt types — Switch to the prompt refinement approach: describe the subject, action, camera angle, and style explicitly. Add negative_prompt entries for common artifacts. If quality is still insufficient for the use case, evaluate the standard Hunyuan Video endpoint.
FAQ
What is the Novita AI endpoint for Hunyuan Video Fast?
POST https://api.novita.ai/v3/async/hunyuan-video-fast. The API is asynchronous: submit a request, receive a task_id, then poll GET https://api.novita.ai/v3/async/task-result?task_id=<id> until task_status is TASK_STATUS_SUCCEED.
How does Hunyuan Video Fast differ from Hunyuan Video standard?
The fast variant is optimized for generation speed — it reduces the time from task submission to completed video. The tradeoff is that motion fidelity and fine-grained prompt adherence are lower than the standard model. Use the fast variant for prompt iteration, high-throughput batch jobs, or staging; use standard for final-quality output.
Can I set a specific video duration?
Check the API reference for supported duration parameters. Some Novita video APIs expose an explicit duration field; others use a model default. Verify before assuming a default clip length.
How do I reproduce a specific video output?
Set seed to a fixed integer. The same seed, prompt, width, and height combination should produce consistent output across runs.
Does Hunyuan Video Fast support image-to-video?
Hunyuan Video Fast on Novita AI is a text-to-video model. For image-to-video generation on Novita, check the available I2V models such as Kling, Vidu, or Wan on the Novita models page.
How much does Hunyuan Video Fast cost on Novita AI?
Verify current pricing at novita.ai/models. Per-clip pricing for video models can change; always check the pricing page before building production cost estimates.
Is Hunyuan Video Fast suitable for production video pipelines?
Yes, with appropriate handling. Design your pipeline around asynchronous task submission, store the task_id for status tracking, download the video immediately after completion (before video_url_ttl expires), and handle TASK_STATUS_FAILED with a retry or fallback strategy.
