Public Video API

Overview

The AVS public API is an async video API for teams that want to trigger AVS creation and rendering from their own systems.

V1 supports:

• prompt -> video job
• json template -> video job
• job polling
• optional completion webhooks
• bearer-token auth using public API tokens

V1 does not expose editor projects, branches, or timeline mutation APIs directly.

Authentication

Create a token in Settings -> API. Tokens use the same bearer format as other AVS machine tokens:

Authorization: Bearer avs.<tokenId>.<secret>

Public API routes accept only public API tokens. CLI tokens do not work on /api/v1/*.

Supported token lifecycle actions in the UI are:

• create
• list
• rotate
• revoke

Endpoints

Create from prompt

POST /api/v1/videos/from-prompt

{
  "prompt": "Create a 20 second product teaser using the uploaded footage.",
  "assetUrls": ["https://example.com/intro.mp4"],
  "output": {
    "aspectRatio": "16:9",
    "quality": "studio"
  },
  "webhook": {
    "url": "https://example.com/webhooks/avs",
    "secret": "whsec_..."
  }
}

You can also send multipart/form-data with:

• request: JSON string containing the same payload
• files: repeated file parts for job-scoped uploads

Use prompt mode when you want AVS to perform more of the creation logic for you.

Create from JSON

POST /api/v1/videos/from-json

{
  "template": {
    "version": "1",
    "name": "Launch teaser",
    "blocks": [
      {
        "type": "video",
        "start": 0,
        "duration": 5,
        "source": { "uploadName": "hero.mp4" }
      },
      {
        "type": "text",
        "start": 0,
        "duration": 5,
        "text": "Now shipping"
      }
    ]
  },
  "output": {
    "aspectRatio": "9:16",
    "quality": "web"
  }
}

Supported block types in AVS Template JSON v1:

• video
• image
• text
• audio

Media blocks must reference either:

• source.url
• source.uploadName

Use JSON mode when your system already knows the structure of the composition and AVS mainly needs to render it.

Poll job status

GET /api/v1/jobs/:jobId

Example response:

{
  "jobId": "job_123",
  "mode": "prompt",
  "status": "running",
  "phase": "rendering",
  "createdAt": "2026-04-07T18:00:00.000Z",
  "updatedAt": "2026-04-07T18:00:08.000Z",
  "error": null,
  "result": null
}

Terminal success includes:

{
  "result": {
    "downloadUrl": "https://...",
    "expiresAt": "2026-04-14T18:00:08.000Z"
  }
}

Job phases

Public jobs move through these phases:

• queued
• preparing_assets
• generating
• rendering
• completed
• failed

Webhooks

When a job reaches a terminal state, AVS can send a webhook to your endpoint.

Headers:

• X-AVS-Event
• X-AVS-Timestamp
• X-AVS-Signature: sha256=<hex>

The signature is an HMAC-SHA256 of the raw request body using the webhook secret you supplied on job creation.

AVS retries failed webhook deliveries up to 3 times with backoff.

This makes the API suitable for external systems that do not want to poll aggressively.

Costs

Public API usage consumes the same user credit balance as the rest of AVS.

Prompt jobs

A prompt job can consume:

• asset upload credits for every uploaded or imported input asset
• 3 R-Credits for the AI creator step
• 5 R-Credits for the final render

JSON jobs

A JSON job can consume:

• asset upload credits for every uploaded or imported input asset
• 5 R-Credits for the final render

Upload costs

Asset inputs passed through the API are charged using the same upload pricing as normal AVS uploads:

Remote asset URLs are treated as uploaded inputs after AVS fetches them, so they follow the same upload pricing rules.

Notes

• V1 output format is MP4 only.
• Assets are job-scoped in V1. There is no reusable public asset library yet.
• Hidden internal AVS projects are created behind each API job for execution and support purposes.
• Public API routes are separate from the editor’s internal mutation routes and from CLI auth routes.