---
title: "Start an asynchronous video job"
method: POST
path: "/api/v1/videos"
---

# Start an asynchronous video job

`POST /api/v1/videos`

## Request

- Base URL: `https://genmagic.co`
- URL: `https://genmagic.co/api/v1/videos`
- Auth: HTTP bearer

Returns 202 immediately with { id, object: "video.generation", model, status: "queued", created (Unix seconds), status_url }; nothing is charged until the clip completes. Poll GET /api/v1/videos/{id} until status is completed or failed.

## Request body

- object
  - `prompt` string, required: Description of the video.
  - `model` string: Model id. Omit for the default. Must be a text-to-video model (capabilities.text_to_video in GET /api/v1/models?category=video); a model that edits, upscales or animates supplied media is refused with 400 model_not_supported.
  - `aspect_ratio` '16:9' | '9:16' | '1:1': Defaults to 16:9.
  - `duration` integer: Clip length in seconds, one of the model's pricing.video.durations_seconds in GET /api/v1/models?category=video. Omit for the model's default (usually 5). The price scales with it.
  - `resolution` string: One of the model's pricing.video.resolutions, for example 720p. Omit for the model's default. The price scales with it: pricing.video.usd_per_second lists the rate at each resolution.
  - `generate_audio` boolean: Whether to add sound, for a model whose pricing.video.audio_supported is true. Omit for the model's default; sound can roughly double the price (pricing.video.usd_per_second_with_audio).
  - `image` string: Image-to-video: an https URL or data:image URL the clip opens on; the prompt then describes the motion. For a model whose capabilities.frame_images includes first_frame (400 model_not_supported otherwise, 400 invalid_image for an unusable image). Most models bill it like text-to-video; where one does not, its pricing.video carries image_to_video_usd_per_second (a rate of its own) or image_input_usd (a fee for each image supplied).
  - `last_frame` string: An https URL or data:image URL the clip ends on, for a model whose capabilities.frame_images includes last_frame.

## Response `202`

Accepted: async job created.

## Other responses

- `401`: authentication_error: missing or invalid API key.
- `402`: insufficient_quota: credit balance would go negative.
- `429`: rate_limit_error: over 300 requests/minute for this key.

---

[API](https://skmtc.dev/genmagic/apis/genmagic-api.md) · [All operations](https://skmtc.dev/genmagic/apis/genmagic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/genmagic/apis/genmagic-api/revisions/c75319e568f6?raw)