---
title: "Render a free preview after upgrading"
method: POST
path: "/v1/videos/{video_id}/render"
tags: ["Videos"]
---

# Render a free preview after upgrading

`POST /v1/videos/{video_id}/render`

## Request

- Base URL: `https://api.vivideo.ai`
- URL: `https://api.vivideo.ai/v1/videos/{video_id}/render`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/vivideo/apis/vivideo-api/docs/v1/videos/:video_id/render/post.ts> (a function with typed inputs; its response is checked against the schema)

Renders a `status: "preview"` video for real once the account is
premium. The first video after upgrading is free (comped); later renders
charge the normal credit price. Idempotent — if the video is already
rendering or done, the current state is returned without a second charge.

## Path parameters

- `video_id` string, required

## Response `200`

Render started (or current state if already rendered).

- Video
  - `id` string
  - `object` string
  - `mode` 'auto' | 'manual'
  - `model` string
  - `status` 'queued' | 'processing' | 'completed' | 'failed' | 'preview'
  - `name` string
  - `folder_id` string
  - `created_at` string
  - `credits_charged` number
  - `poll_interval_seconds` integer
  - `video_url` string: Present when status=completed.
  - `video_url_no_captions` string
  - `caption_url` string
  - `thumbnail_url` string
  - `duration_seconds` number
  - `progress` object
    - `status` string
    - `queue_position` integer, nullable
    - `percent` number, nullable
  - `error` object
    - `code` string
    - `message` string
    - `credits_refunded` boolean
  - `preview` object: Present when status=preview (free-account funnel).
    - `image_url` string, nullable: Low-res preview image — display blurred.
    - `image_note` string
    - `message` string
    - `upgrade_url` string

## Other responses

- `401`: Missing, malformed or revoked API key (`missing_api_key`, `invalid_api_key`, `api_key_revoked`).
- `402`: Not enough credits (`insufficient_credits`); `links.buy_credits` points to the top-up page.
- `403`: Premium plan required or the free allowance is used (`upgrade_required`, `free_limit_reached`); `links.upgrade` = https://app.vivideo.ai/upgrade.
- `404`: The resource does not exist for this account (`not_found`).
- `429`: Rate limit hit (`rate_limited`). Honor the `Retry-After` header / `retry_after_seconds` field.

---

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