Video generation

Video generation is an asynchronous workflow: you submit a job, the worker runs the upstream generation, and you poll for the finished media. Like every other request it authenticates with your API key, holds wallet credit up front, and settles usage through the standard billing path.

POST   /v1/jobs        # kind: "video_generation"
GET    /v1/jobs/:id     # poll status + result
GET    /v1/jobs
DELETE /v1/jobs/:id     # cancel a queued job

Discover video-capable models from the catalog:

curl "https://api.onehop.ai/v1/models?output_modality=video" \
  -H "Authorization: Bearer $ONEHOP_API_KEY"

Generation modes

Different models support different input modes. A job is validated against the model's declared capabilities before anything is sent upstream, so an unsupported combination fails fast with a clear OneHop error rather than an opaque provider error.

Text to video

A prompt with no input frames. Requires the model's text-to-video capability.

Image to video

A single first frame drives the motion. Requires image-to-video.

First & last frame

Interpolate between a start and end frame. Requires both first-last-frame support and a first frame present.

Reference image

Guide generation with one or more reference images.

If you request a mode a model doesn't support, OneHop returns a specific error before billing — for example MODEL_NO_TEXT_TO_VIDEO, MODEL_NO_IMAGE_TO_VIDEO, MODEL_NO_LAST_FRAME, MODEL_NO_REFERENCE_IMAGE, or MODEL_FRAME_REQUIRES_FIRST when a last frame is sent without a first frame.

Polling for the result

GET /v1/jobs/:id returns the current status. Once a job is completed, the response includes a freshly signed URL for the generated media. List responses do not sign large object URLs — fetch the individual job to get a download link.

Use an idempotency key

Video jobs are expensive and slow. Always send X-Idempotency-Key so a retried submission returns the existing job instead of starting a second generation.

Billing for video

How a video model is priced depends on its billing style:

Style	Quantity
`token`	Output tokens parsed from the upstream response
`per_second`	Duration in seconds × sample count
`per_call`	Sample count, optionally tiered by resolution and duration

Resolution, duration, sample count, and mode (t2v / i2v) are recorded when the job is created so pricing is deterministic. The authoritative billed amount always comes from OneHop's own pricing engine — see Billing & wallet.