Chat completions

Create and retrieve video generations via the OpenAI-compatible chat completions API.

Pipevideo supports the OpenAI Chat Completions API shape for video generation. Send messages with text, image, or video content parts; responses return video URLs in choices[0].message.video_url instead of text.

New integrations: Prefer the Responses API — it matches OpenAI's newer responses.create shape and includes output_video_url plus typed output items. Chat completions remain fully supported for existing OpenAI SDK integrations that use chat.completions.create.

Create generation

POST /v1/chat/completions

Authentication: API key required

Request body

Parameter	Type	Required	Description
`model`	`string`	Yes	Orchestration LLM id (e.g. `moonshotai/kimi-k2.5`). Not an engine slug.
`messages`	`array`	Yes	OpenAI-style chat messages with text, image, or video content parts.
`engine`	`string`	No	`hyperframes`, `lottie`, or `auto`. Default: `hyperframes`.
`expand_prompt`	`boolean`	No	Improve the prompt with the engine's prompting guide first.
`width`	`number`	No	Canvas width in pixels. Default `1080`.
`height`	`number`	No	Canvas height in pixels. Default `1920`.
`aspectRatio`	`string`	No	Aspect ratio hint (e.g. `16:9`).
`provider`	`object`	No	Provider routing. See Provider routing.
`webhook_url`	`string`	No	HTTPS URL to receive lifecycle webhooks for this generation. Must be publicly reachable (localhost and private IPs are rejected).

Example

curl -X POST https://api.pipevideo.co/v1/chat/completions \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/kimi-k2.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "A cat walking on a beach at sunset" }
        ]
      }
    ],
    "webhook_url": "https://example.com/webhooks/pipevideo",
    "provider": { "order": ["framerate"] }
  }'

For multimodal prompts, use OpenAI-style content part types (text, image_url, video_url). See Multimodal inputs.

Create response

{
  "id": "gen_abc123xyz",
  "object": "chat.completion",
  "status": "pending",
  "model": "moonshotai/kimi-k2.5",
  "engine": "hyperframes",
  "provider": "framerate",
  "created": 1709827200,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "video_url": null
      },
      "finish_reason": null
    }
  ],
  "usage": null
}

Get generation

GET /v1/chat/completions/{id}

Authentication: API key required

Retrieve the current status and result of a generation. Poll until status is completed, failed, or cancelled.

Response fields

Field	Type	Description
`id`	`string`	Generation ID
`object`	`string`	Always `chat.completion`
`status`	`string`	`pending`, `processing`, `completed`, `failed`, or `cancelled`
`model`	`string`	Orchestration model id
`engine`	`string`	Rendering engine (e.g. `hyperframes`)
`provider`	`string` \| `null`	Video orchestration provider slug
`choices`	`array`	Video URL in `choices[0].message.video_url` when completed
`usage`	`object` \| `null`	Token usage and `cost_usd` when available
`latency_ms`	`number` \| `null`	End-to-end latency when completed
`error`	`object` \| `null`	`{ message, type }` when failed or cancelled
`created`	`number`	Unix timestamp (seconds)
`completed_at`	`number` \| `null`	Completion timestamp (milliseconds)
`artifact_url`	`object` \| `null`	Native engine artifact URL (e.g. Lottie JSON) when produced
`artifact_type`	`string` \| `null`	Media type of `artifact_url`

Completed response example

{
  "id": "gen_abc123xyz",
  "object": "chat.completion",
  "status": "completed",
  "model": "moonshotai/kimi-k2.5",
  "engine": "hyperframes",
  "provider": "framerate",
  "created": 1709827200,
  "completed_at": 1709827260000,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "video_url": {
          "url": "https://storage.example.com/videos/abc123.mp4",
          "expires_at": 1709913660
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 3400,
    "total_tokens": 4600,
    "cost_usd": 0.12
  },
  "latency_ms": 58000
}

Cancel generation

DELETE /v1/chat/completions/{id}

Authentication: API key required

Cancel an in-flight generation. Returns { "id": "...", "cancelled": true }.

Status transitions

pending → processing → completed
                   → failed
                   → cancelled

Transitions are one-way. Poll every 2–5 seconds, or pass webhook_url on create to receive webhook events instead.

Responses API equivalent

Chat completions	Responses API
`messages`	`input` (+ optional `instructions`)
`choices[0].message.video_url`	`output_video_url` and `output` items
`status: "pending"`	`status: "queued"`
`status: "processing"`	`status: "in_progress"`
`aspectRatio`	`aspect_ratio`
Content parts: `text`, `image_url`, `video_url`	Content parts: `input_text`, `input_image`, `input_video`

Both APIs create the same underlying generation — use whichever shape fits your client.

Responses API — recommended for new integrations
Video generation guide — end-to-end flow with error handling
Multimodal inputs — text, image, and video content parts
OpenAI SDK — use chat.completions.create with Pipevideo
Errors — HTTP status codes and error handling

On this page