---
title: "Create a video generation task in the OpenAI Videos shape"
method: POST
path: "/v1/videos"
tags: ["OpenAI Compatible"]
---

# Create a video generation task in the OpenAI Videos shape

`POST /v1/videos`

## Request

- Base URL: `https://api.popnow.ai`
- URL: `https://api.popnow.ai/v1/videos`
- Auth: HTTP bearer

Projection of `createTask` onto the OpenAI Videos API. `model` must be
a video endpoint identifier from `/v1/models`. `prompt` maps to the
model's `prompt`; `input_reference` (an HTTPS URL or a committed
`popnow://` upload) maps to `image_url` / `image_urls`; `seconds` maps to
`duration_seconds`; `size` (`WIDTHxHEIGHT`) maps to `resolution` and/or
`aspect_ratio`, or to `width` / `height` when the model declares pixel
dimensions. A parameter the selected model does not declare is
rejected with `400`. The same hold and idempotency rules as
`createTask` apply; the returned object never contains prices.

## Headers

- `Idempotency-Key` string

## Request body

- VideoCreateRequest
  - `model` string, required: Video endpoint identifier from `/v1/models`.
  - `prompt` string, required
  - `input_reference` string: Reference image URL; mapped to the model's `image_url` / `image_urls`.
  - `seconds` union: Clip length in seconds; mapped to `duration_seconds`.
    - string
    - integer
  - `size` string: WIDTHxHEIGHT, mapped to `resolution` / `aspect_ratio` (or `width` / `height`).

## Response `200`

The accepted task as a `video` object in `queued` state (an idempotent replay reports the current state).

- Video
  - `id` string, required: Task identifier; also accepted by `/api/v1/jobs/recordInfo`.
  - `object` 'video', required
  - `model` string, required
  - `status` 'queued' | 'in_progress' | 'completed' | 'failed', required
  - `progress` integer, required: 100 when completed, otherwise 0; no fabricated intermediate values.
  - `created_at` integer, required
  - `completed_at` integer
  - `seconds` string
  - `size` string
  - `error` object
    - `code` string, required
    - `message` string, required

## Other responses

- `400`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `401`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `402`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `403`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `404`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `409`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `413`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `429`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `500`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).
- `503`: Error in the OpenAI `{error:{message,type,param,code}}` shape. The HTTP status is the same one `/api/v1` would return. A content-policy refusal is HTTP 400 with `code: content_rejected`, so it can be told apart from a parameter error (`invalid_request` / `unsupported_parameter`, with `param` set when the error is about one field).

---

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