Video Generation API
Create, monitor, and download asynchronous video generations through Your Model.
The Video Generation API provides one asynchronous interface for compatible text-to-video, image-to-video, and reference-video models.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v1/video/generations | Submit a video generation task. |
GET | /v1/video/generations/{task_id} | Read the latest stored task status and result. |
GET | /v1/videos/{task_id}/content | Download or stream the completed video. |
All requests require an API key:
Authorization: Bearer YOUR_MODEL_API_KEYCreate a video
Text to video
curl https://y-models.com/v1/video/generations \
-H "Authorization: Bearer YOUR_MODEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "artsdance-2-0-mini-260801",
"prompt": "A paper boat crossing a rain-filled neon street",
"resolution": "720p",
"duration": 5
}'Image to video
images accepts URL strings and objects with a url property. Additional
object properties, such as a provider-supported role, are forwarded.
curl https://y-models.com/v1/video/generations \
-H "Authorization: Bearer YOUR_MODEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "artsdance-2-0-mini-260801",
"prompt": "The camera slowly moves toward the subject",
"resolution": "1080p",
"duration": 5,
"images": [
{
"url": "https://example.com/first-frame.png",
"role": "first_frame"
}
]
}'Reference video
Use videos, video_url, or a video item in content when the selected model
supports video references. A request containing a reference video uses the
corresponding reference-video price tier.
curl https://y-models.com/v1/video/generations \
-H "Authorization: Bearer YOUR_MODEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "artsdance-2-0-mini-260801",
"prompt": "Preserve the motion while changing the scene to watercolor",
"resolution": "1080p",
"duration": 5,
"videos": [
{
"url": "https://example.com/reference.mp4",
"role": "reference_video"
}
]
}'Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | A video-capable model ID. |
prompt | string | Yes | The generation or transformation instruction. Blank prompts are rejected. |
resolution | string | No | Requested output resolution, such as 480p, 720p, 1080p, or 4k. Model support varies. The billing default is 720p when omitted or unrecognized. |
duration | integer or numeric string | No | Requested duration in seconds. Values above 3,600 or below zero are rejected. |
seconds | string | No | Compatibility alias for duration. |
images | array | No | Image URLs or objects containing url; suitable for first/last-frame or other provider-supported image inputs. |
image | string | No | Compatibility field for one image URL. |
input_reference | string | No | Compatibility field for one image reference. |
video_url | string | No | One reference-video URL. |
videos | array | No | Reference-video values or provider-compatible video objects. |
content | any | No | Provider-compatible structured content. Video or reference-video items are recognized for billing. |
generate_audio | boolean | No | Requests audio generation when the selected model and route support it. |
metadata | object or JSON string | No | Provider-specific metadata. |
The gateway preserves additional top-level JSON fields when forwarding a request. Their behavior depends on the selected model and upstream route.
Submission response
A successful submission returns the upstream-compatible task body with a public
task ID. Use the returned id (or compatibility field task_id) for polling.
{
"id": "task_PUBLIC_ID",
"task_id": "task_PUBLIC_ID",
"status": "queued"
}The submit endpoint currently returns HTTP 200 after the task has been
accepted.
Poll a task
curl https://y-models.com/v1/video/generations/task_PUBLIC_ID \
-H "Authorization: Bearer YOUR_MODEL_API_KEY"The generic polling endpoint returns a task wrapper. Important fields include:
{
"code": "success",
"data": {
"task_id": "task_PUBLIC_ID",
"status": "SUCCESS",
"progress": "100%",
"result_url": "https://example.com/generated-video.mp4",
"data": {
"status": "completed",
"usage": {
"total_tokens": 2000000
},
"resolution": "1080p"
}
}
}Stored task statuses are NOT_START, SUBMITTED, QUEUED, IN_PROGRESS,
SUCCESS, and FAILURE. Poll with a sensible interval, such as 5–10 seconds,
until the task reaches a terminal status.
Download the completed video
After SUCCESS, either use result_url or stream the result through the
authenticated content endpoint:
curl -L https://y-models.com/v1/videos/task_PUBLIC_ID/content \
-H "Authorization: Bearer YOUR_MODEL_API_KEY" \
--output generated.mp4JavaScript example
const apiKey = process.env.YOURMODEL_API_KEY;
if (!apiKey) throw new Error('YOURMODEL_API_KEY is not set');
const headers = {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
};
const submitted = await fetch('https://y-models.com/v1/video/generations', {
method: 'POST',
headers,
body: JSON.stringify({
model: 'artsdance-2-0-mini-260801',
prompt: 'A slow aerial shot over a glass forest',
resolution: '720p',
duration: 5,
}),
});
if (!submitted.ok) throw new Error(await submitted.text());
const created = await submitted.json();
const taskId = created.id ?? created.task_id;
let task;
do {
await new Promise((resolve) => setTimeout(resolve, 5000));
const response = await fetch(
`https://y-models.com/v1/video/generations/${taskId}`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
);
if (!response.ok) throw new Error(await response.text());
task = (await response.json()).data;
} while (!['SUCCESS', 'FAILURE'].includes(task.status));
if (task.status === 'FAILURE') throw new Error(task.fail_reason);
console.log(task.result_url);Python example
import os
import time
import requests
api_key = os.environ.get("YOURMODEL_API_KEY")
if not api_key:
raise RuntimeError("YOURMODEL_API_KEY is not set")
headers = {"Authorization": f"Bearer {api_key}"}
response = requests.post(
"https://y-models.com/v1/video/generations",
headers=headers,
json={
"model": "artsdance-2-0-mini-260801",
"prompt": "A slow aerial shot over a glass forest",
"resolution": "720p",
"duration": 5,
},
timeout=60,
)
response.raise_for_status()
created = response.json()
task_id = created.get("id") or created["task_id"]
while True:
task_response = requests.get(
f"https://y-models.com/v1/video/generations/{task_id}",
headers=headers,
timeout=60,
)
task_response.raise_for_status()
task = task_response.json()["data"]
if task["status"] in {"SUCCESS", "FAILURE"}:
break
time.sleep(5)
if task["status"] == "FAILURE":
raise RuntimeError(task.get("fail_reason") or "Video generation failed")
print(task["result_url"])Models
| Model | Supported resolutions | Reference video | Billing basis | Execution |
|---|---|---|---|---|
artsdance-2-0-fast-260801 | 480p, 720p, 1080p | Yes | Final total_tokens | Asynchronous |
artsdance-2-0-mini-260801 | 480p, 720p, 1080p | Yes | Final total_tokens | Asynchronous |
artsdance-2-0-pro-260801 | 480p, 720p, 1080p, 4K | Yes | Final total_tokens | Asynchronous |
artsdance-2-5-pro-260801 | 720p, 1080p | Yes | Final total_tokens | Asynchronous |
Send the shortest duration accepted by the selected model when minimizing test
cost. Exact duration choices can vary by upstream model revision; the gateway
accepts the duration or seconds field and rejects values outside its global
safety bound.
Pricing
Prices below are in USD per 1 million final total_tokens. "With reference
video" means the request contains a reference through video_url, videos, or
structured content. Image references alone use the without-reference-video
tier.
| Model | Resolution | With reference video | Without reference video |
|---|---|---|---|
artsdance-2-0-fast-260801 | 480p / 720p | $2.2647 | $3.8088 |
artsdance-2-0-fast-260801 | 1080p | $2.5221 | $4.3235 |
artsdance-2-0-mini-260801 | 480p / 720p | $1.0294 | $1.6912 |
artsdance-2-0-mini-260801 | 1080p | $1.1397 | $1.8750 |
artsdance-2-0-pro-260801 | 480p / 720p | $3.0882 | $5.0735 |
artsdance-2-0-pro-260801 | 1080p | $3.4191 | $5.6250 |
artsdance-2-0-pro-260801 | 4K | $1.7647 | $2.8676 |
artsdance-2-5-pro-260801 | 720p | $4.9412 | $8.2353 |
artsdance-2-5-pro-260801 | 1080p | $5.4706 | $9.0588 |
These USD rates are converted from the current RMB source prices at RMB 6.8 per USD.
The live pricing page is the source of truth for currently enabled models and rates.
How settlement works
- Submission reserves an estimated amount using the request resolution and whether it contains a reference video.
- The task keeps that price expression and group ratio as a snapshot, so a later administrator price edit does not change an in-flight task.
- On completion, billing is recalculated from the provider's final
total_tokensand authoritative output resolution. Only the difference from the reservation is charged or refunded. - A failed asynchronous task refunds its reserved amount. An immediately rejected request, including an upstream insufficient-balance response, does not retain a completed-task charge.
Errors
| Status | Meaning |
|---|---|
400 | Missing model or prompt, invalid JSON, invalid duration, unsupported request, or a task that is not ready for content download. |
401 | Missing, invalid, or revoked API key. |
402 | Insufficient Your Model balance or an upstream billing rejection. |
404 | The task does not exist or does not belong to the authenticated user. |
429 | Rate limited; retry with backoff. |
5xx | The gateway or selected upstream route could not complete the operation. |
Do not retry a submission blindly after a network timeout. First check whether the client received a task ID or whether a task appears in usage history, then submit again only when you know a duplicate will not be created.