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"
}

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 images for style guidance (reference-to-video)

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.mp4

Raw 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.