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/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Available Models

curl https://perceptron.cloud/api/v1/videos/models

Generating 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"
}
FieldTypeRequiredDescription
modelstringyesVideo model ID from GET /api/v1/videos/models
promptstringyesText description of the video to generate
durationintegeryesClip duration in seconds (per-model min/max)
resolutionstringnoOutput resolution tier (e.g. 2K); defaults to the model’s first supported tier
aspect_ratiostringnoAspect ratio (e.g. 16:9, 9:16, 1:1)
sizestringnoExact pixel dimensions in WIDTHxHEIGHT format; interchangeable with resolution + aspect_ratio
generate_audiobooleannoWhether to generate audio alongside the video (models with audio support)
seedintegernoSeed for deterministic generation (not guaranteed by all models)
frame_imagesarraynoFirst/last frame images (image-to-video), each with a frame_type of first_frame or last_frame
input_referencesarraynoReference 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_idstringnoId of one of your completed video jobs to extend or edit (the model must support it)
edit_modestringnoextend (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 }
}
StatusDescription
pendingThe job is queued
in_progressThe video is being generated
completedThe video is ready to download
failedGeneration failed (see error); the reservation is fully refunded
cancelledThe job was cancelled upstream; fully refunded
expiredThe 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.mp4

Raw video bytes with Content-Type: video/mp4. Finished videos are stored as artifacts in your account.

Listing and deleting jobs

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.