Video
Perceptron provides a video generation API. Video models accept text prompts (and optional reference images) and generate video clips.
Video generation is asynchronous: you submit a job, poll its status, and download the finished video. Generation typically takes a few minutes.
Base URL
https://perceptron.cloud/api/v1Authentication
Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYAvailable Models
curl https://perceptron.cloud/api/v1/videos/modelsGenerating Videos
1. Submit a job
POST /api/v1/videos
curl -X POST https://perceptron.cloud/api/v1/videos \
-H "Authorization: Bearer $PERCEPTRON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax/hailuo-3",
"prompt": "A golden retriever playing fetch on a sunny beach with waves crashing in the background",
"duration": 5,
"resolution": "2K",
"aspect_ratio": "16:9"
}'Returns 202 Accepted with the job details:
{
"id": "0e1b0c3f-...",
"polling_url": "/api/v1/videos/0e1b0c3f-...",
"status": "pending"
}| Field | Type | Required | Description |
|---|---|---|---|
model | string | yes | Video model ID from GET /api/v1/videos/models |
prompt | string | yes | Text description of the video to generate |
duration | integer | yes | Clip duration in seconds (per-model min/max) |
resolution | string | no | Output resolution tier (e.g. 2K); defaults to the model’s first supported tier |
aspect_ratio | string | no | Aspect ratio (e.g. 16:9, 9:16, 1:1) |
size | string | no | Exact pixel dimensions in WIDTHxHEIGHT format; interchangeable with resolution + aspect_ratio |
generate_audio | boolean | no | Whether to generate audio alongside the video (models with audio support) |
seed | integer | no | Seed for deterministic generation (not guaranteed by all models) |
frame_images | array | no | First/last frame images (image-to-video), each with a frame_type of first_frame or last_frame |
input_references | array | no | Reference assets: image_url, video_url, and audio_url content parts, or {artifact_id, start?, end?} entries that select a segment of a stored video/audio artifact |
previous_job_id | string | no | Id of one of your completed video jobs to extend or edit (the model must support it) |
edit_mode | string | no | extend (default) or edit, used with previous_job_id |
frame_images and input_references are separate conditioning modes: a request may use one or the other, never both. Each model declares the reference kinds it accepts in supported_input_references (from GET /api/v1/videos/models), along with per-kind counts (max_input_videos, max_input_audios) and a combined duration budget (max_reference_seconds). Segment selections are cut into a derived clip artifact before submission, so the provider receives exactly the segment you asked for.
# Reference-to-video with a trimmed source clip + a style image
curl -X POST https://perceptron.cloud/api/v1/videos \
-H "Authorization: Bearer $PERCEPTRON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedance-2.5",
"prompt": "the same camera move, now at dusk",
"duration": 8,
"resolution": "720p",
"input_references": [
{"artifact_id": "6c1f...", "start": 1.5, "end": 7.0},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]
}'2. Poll for status
GET /api/v1/videos/{id}
curl https://perceptron.cloud/api/v1/videos/0e1b0c3f-... \
-H "Authorization: Bearer $PERCEPTRON_API_KEY"{
"id": "0e1b0c3f-...",
"polling_url": "/api/v1/videos/0e1b0c3f-...",
"status": "completed",
"unsigned_urls": ["/api/v1/videos/0e1b0c3f-.../content?index=0"],
"usage": { "cost": 1.5 }
}| Status | Description |
|---|---|
pending | The job is queued |
in_progress | The video is being generated |
completed | The video is ready to download |
failed | Generation failed (see error); the reservation is fully refunded |
cancelled | The job was cancelled upstream; fully refunded |
expired | The job exceeded its upstream time limit; fully refunded |
Poll at a reasonable interval (e.g. every 5–30 seconds).
3. Download the video
GET /api/v1/videos/{id}/content
curl https://perceptron.cloud/api/v1/videos/0e1b0c3f-.../content \
-H "Authorization: Bearer $PERCEPTRON_API_KEY" \
--output video.mp4Raw video bytes with Content-Type: video/mp4. Finished videos are stored as artifacts in your account.
Listing and deleting jobs
- GET
/api/v1/videos: list your video generation jobs, newest first. - DELETE
/api/v1/videos/{id}: delete a job and its stored video, stopping its storage billing.
See the full reference at API Reference.
Pricing
Video generation is billed per output second from your credits balance. See the live per-resolution rates at GET /api/v1/videos/models. See Billing for more details.
Studio
The Perceptron app includes Perceptron Studio, a creative studio interface for generating and managing videos without writing any code: open the app and select Studio in the sidebar menu.