Responses

Pipevideo uses an OpenAI Responses-compatible API for video generation. Send input (and optional instructions); responses return typed output items with video URLs instead of text.

Create generation

POST /v1/responses

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.
`input`	`string` \| `array`	Yes	Prompt text or conversation input items.
`instructions`	`string`	No	System-level guidance, separate from conversation input.
`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.

Example

curl -X POST https://api.pipevideo.co/v1/responses \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/kimi-k2.5",
    "input": "A cat walking on a beach at sunset",
    "provider": { "order": ["framerate"] }
  }'

For multimodal prompts, pass input as an array of message items:

{
  "model": "moonshotai/kimi-k2.5",
  "instructions": "You are a motion designer.",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Animate this logo with a smooth fade-in" },
        { "type": "input_image", "image_url": { "url": "https://example.com/logo.png" } }
      ]
    }
  ]
}

Create response

{
  "id": "gen_abc123xyz",
  "object": "response",
  "status": "queued",
  "model": "moonshotai/kimi-k2.5",
  "engine": "hyperframes",
  "provider": "framerate",
  "created_at": 1709827200,
  "output": [
    {
      "type": "message",
      "id": "gen_abc123xyz_msg",
      "role": "assistant",
      "status": "in_progress",
      "content": []
    }
  ],
  "output_video_url": null,
  "usage": null
}

Get generation

GET /v1/responses/{id}

Authentication: API key required

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

Response fields

Field	Type	Description
`id`	`string`	Generation ID
`object`	`string`	Always `response`
`status`	`string`	`queued`, `in_progress`, `completed`, `failed`, `cancelled`, or `incomplete`
`model`	`string`	Orchestration model id
`engine`	`string`	Rendering engine (e.g. `hyperframes`)
`provider`	`string` \| `null`	Video orchestration provider slug
`output`	`array`	Typed output items — video URL in `output_video` content parts when completed
`output_video_url`	`string` \| `null`	Convenience URL for the generated video (like OpenAI's `output_text`)
`usage`	`object` \| `null`	Token usage and `cost_usd` when available
`latency_ms`	`number` \| `null`	End-to-end latency when completed
`error`	`object` \| `null`	`{ code, message }` when failed
`created_at`	`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": "response",
  "status": "completed",
  "model": "moonshotai/kimi-k2.5",
  "engine": "hyperframes",
  "provider": "framerate",
  "created_at": 1709827200,
  "completed_at": 1709827260000,
  "output": [
    {
      "type": "message",
      "id": "gen_abc123xyz_msg",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_video",
          "video_url": {
            "url": "https://storage.example.com/videos/abc123.mp4",
            "expires_at": 1709913660
          }
        }
      ]
    }
  ],
  "output_video_url": "https://storage.example.com/videos/abc123.mp4",
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 3400,
    "total_tokens": 4600,
    "cost_usd": 0.12
  },
  "latency_ms": 58000
}

Cancel generation

DELETE /v1/responses/{id}

Authentication: API key required

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

Status transitions

queued → in_progress → completed
                    → failed

Transitions are one-way. Poll every 2–5 seconds. For production, prefer webhooks.

Video generation guide — end-to-end flow with error handling
Multimodal inputs — text, image, and video content parts
Errors — HTTP status codes and error handling

On this page