Get API key

Build with AI

For AI agents

The Vivideo API is designed to be called by LLMs and autonomous agents, not just humans. Consistent JSON, stable error codes, and machine-readable specs make code generation reliable.

Machine-readable entry points

openapi.yaml

The complete OpenAPI 3.0 spec — every endpoint, schema and example. Point your codegen or agent at it.

llms-api.txt

A compact, plain-text API summary written for LLM context windows.

Interactive reference

Browse and try every endpoint, generated from the same spec.

i
One spec, always in sync. The interactive reference, the OpenAPI file and the text summary are all generated from the live implementation — so what an agent reads is what the API actually does.

Guidance for agents

If you're building an agent that generates videos on a user's behalf, follow these rules:

  • Check GET /v1/me first — read plan, premium and credits before an expensive call, and surface the returned links (upgrade / buy credits) to the user when relevant.
  • Always send an Idempotency-Key on POST /v1/videos so a retried call never creates or charges twice. On 409 duplicate_request, reuse details.existing_video_id.
  • Poll at poll_interval_seconds (usually 5s), not in a tight loop. Rendering takes seconds to a few minutes — set the user's expectations.
  • Branch on error.code, never on message text. Every error tells you whether it's retryable.
  • Handle the free-tier preview — a status: "preview" response means the account is free; show preview.image_url (blurred) and the upgrade_url, then render with POST /v1/videos/{id}/render after upgrade.

Minimal agent loop

pseudocode
account = GET /v1/me
if not account.premium and not account.free_video_available:
    tell user → account.links.upgrade

video = POST /v1/videos  { mode, model, prompt, ... }   # + Idempotency-Key
while video.status in ("queued", "processing"):
    wait video.poll_interval_seconds
    video = GET /v1/videos/{video.id}

if video.status == "completed":  deliver video.video_url
elif video.status == "preview":  show preview.image_url + upgrade_url
else:                            report video.error.message  # credits refunded

MCP, CLI & Skills

This REST API is the foundation. A Vivideo MCP server, CLI, and agent Skills are built on top of it — so the same capabilities are available natively inside Claude, Cursor, terminals and your own agents. More here soon.

← Previous
Errors & rate limits
Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.