Video Generation
Generate videos from text or images, extend clips, and poll for results.
Video generation is asynchronous: you submit a job, receive a record with a status, and poll the
job until it is completed. Discover video models with the Models API
(GET /v1/models?type=video_generation).
Generate a video
POST /v1/videos/generationsParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Video model id. |
prompt | string | Yes | Text description of the video. |
duration | integer | No | Length in seconds (1–60). Default 5. |
aspect_ratio | string | No | 16:9 (default), 9:16, 1:1, 4:3, or 3:4. |
resolution | string | No | 720p, 1080p (default), or 4k. |
negative_prompt | string | No | What to avoid in the video. |
seed | integer | No | Seed for reproducibility. |
with_audio | boolean | No | Generate audio alongside the video. Default true. |
Each model honors its own subset of these options (resolutions, durations, audio). Check
GET /v1/models/{model_id} for what a given model supports.
Response
The endpoint returns a job record. While the video renders, status is pending or processing:
{
"id": "video_abc123",
"status": "processing",
"created_at": 1709251200,
"model": "model-id",
"prompt": "A drone flyover of a tropical beach at golden hour",
"duration": 5,
"provider": "google"
}When finished, status is completed and the output is available via url (and videos[] for
multi-clip results, plus an optional thumbnail_url). On failure, status is failed and error
describes why.
Image-to-video
POST /v1/videos/image-to-videoAnimate a still image into a clip.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Video model id. |
image | string | Yes | Base64-encoded image or an image URL. |
prompt | string | No | Optional motion description. |
duration | integer | No | Length in seconds (1–30). Default 5. |
motion_strength | number | No | Amount of motion to add, 0.0–1.0. Default 0.5. |
Extend a video
POST /v1/videos/extensionsContinue a previously generated video.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Video model id. |
video_id | string | Yes | Id of the video to extend. |
duration | integer | No | Additional seconds (1–30). Default 5. |
prompt | string | No | Optional prompt for the extension. |
direction | string | No | forward (default) or backward. |
Poll a video
GET /v1/videos/{id}Returns the current job record (same shape as the create response). Poll until status is completed
or failed.
Delete a video
DELETE /v1/videos/{id}Removes the job and its generated assets.
Example
import os, time, httpx
BASE = "https://api.yuhuanstudio.com/v1"
headers = {"Authorization": f"Bearer {os.environ['YUNXIN_API_KEY']}"}
# Submit the generation job
job = httpx.post(
f"{BASE}/videos/generations",
headers=headers,
json={
"model": "model-id",
"prompt": "Ocean waves crashing on a rocky shore, cinematic",
"duration": 5,
},
).json()
video_id = job["id"]
# Poll until the job finishes
while True:
status = httpx.get(f"{BASE}/videos/{video_id}", headers=headers).json()
if status["status"] == "completed":
print(f"Video ready: {status['url']}")
break
if status["status"] == "failed":
print(f"Generation failed: {status.get('error')}")
break
time.sleep(5)Video models are provider-specific and may not be enabled on every account. List what's available with
GET /v1/models?type=video_generation.
How is this guide?