Public Video API

Overview

The AVS public API is a high-level async video API for teams that want to automate video production from their own systems.

V1 supports:

• prompt -> mp4
• json -> mp4
• job polling
• optional completion webhooks

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/*.

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

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

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.

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.