# Avatarity Developer API Specification (llms.txt)
> Wholesale programmatic access to Google Veo 3.1 video generation, Nano Banana Pro 8K packaging, and autonomous fleet queue telemetry.
> Version: 2.1.0 | Protocol: OpenAPI 3.1.0 | Base URL: https://avatarity.dev

---

## 1. Authentication
All requests to `/api/v1/*` require a Bearer token in the `Authorization` header:

```http
Authorization: Bearer vf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Alternatively, server-to-server integrations may pass `X-API-Key`:
```http
X-API-Key: vf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## 2. V1 Frontier Ingress API Contracts (`/v1/*`)

### 2.1 POST /v1/video/create
Initiates an asynchronous video synthesis job with priority QoS routing.
- **Method**: `POST`
- **Path**: `/v1/video/create`
- **Request Body**:
```json
{
  "model": "veo-3.1-lite",
  "prompt": "Cinematic wide-angle drone shot skimming over sandstone spires at sunrise --ar 16:9",
  "priority": "turbo",
  "aspect_ratio": "16:9",
  "duration": 10,
  "webhook_url": "https://client.api.com/webhooks/avatarity"
}
```
**Priority Lane Matrix**:
- `turbo`: 80 units ($0.080) | ~14s ETA | 0ms wait, dedicated GPU lane
- `standard`: 40 units ($0.040) | ~28s ETA | <25s dispatch SLA
- `spot`: 20 units ($0.020) | ~45s ETA | Opportunistic harvest, 50% discount
- `backfill`: 0 units ($0.000) | ~60s ETA | Unmetered autonomous sovereign fleet surplus

**Response (HTTP 202 Accepted)**:
```json
{
  "task_id": "task_01j8x2k4m9v5q7y3",
  "status": "queued",
  "model": "veo-3.1-lite",
  "priority": "turbo",
  "estimated_cost_units": 80,
  "estimated_cost_usd": 0.08,
  "eta_seconds": 14,
  "links": {
    "query": "/v1/video/query?task_id=task_01j8x2k4m9v5q7y3"
  }
}
```

### 2.2 GET /v1/video/query
Polls execution state, real-time progress bar (0-100%), video player URL, and actual cost deducted.
- **Method**: `GET`
- **Path**: `/v1/video/query?task_id=task_01j8x2k4m9v5q7y3`
**Response (HTTP 200 OK - Succeeded)**:
```json
{
  "task_id": "task_01j8x2k4m9v5q7y3",
  "status": "succeeded",
  "progress_pct": 100,
  "elapsed_seconds": 32,
  "worker_node": "VPS-1-Node-01 (Helsinki)",
  "video_url": "https://avatarity.dev/videos/elbsandsteingebirge_smooth_60fps.mp4",
  "thumbnail_url": "https://avatarity.dev/images/thumbnails/thumb_megastructure_ringworld_shadow_squares_orbit.jpg",
  "duration_seconds": 10,
  "lane": "turbo",
  "actual_cost_units": 80,
  "actual_cost_usd": 0.08,
  "completed_at": "2026-09-30T16:00:32.000Z"
}
```

### 2.3 POST /v1/images/generations (OpenAI Format)
Generates high-CTR packaging thumbnails drop-in compatible with standard OpenAI SDKs.
- **Method**: `POST`
- **Path**: `/v1/images/generations`
- **Request Body**:
```json
{
  "model": "nano-banana-pro",
  "prompt": "High CTR YouTube thumbnail: An ancient cybernetic monk in obsidian datacenter vault --ar 16:9",
  "n": 1,
  "size": "1792x1024",
  "response_format": "url"
}
```
**Response (HTTP 200 OK)**:
```json
{
  "created": 1759248000,
  "data": [
    {
      "url": "https://avatarity.dev/images/thumbnails/thumb_megastructure_ringworld_shadow_squares_orbit.jpg"
    }
  ]
}
```

### 2.4 GET /v1/models
Lists models with operational capabilities, hardware targets, and spot benchmark index.
- **Method**: `GET`
- **Path**: `/v1/models`
- **Response**: Array of models including `veo-3.1-lite` (0 units, p50: 34s), `veo3-fast` (25 units, p50: 14s), `nano-banana-pro` (15 units, 8K).

### 2.5 GET /v1/health
Public real-time telemetry for 100% capacity saturation, 18 worker nodes, queue depth per lane, and p50/p95 latency.
- **Method**: `GET`
- **Path**: `/v1/health`
- **Response**: Saturated capacity split (`externalUserDemandPct`, `internalBackfillPct`), `queueDepthByLane` (`turbo`, `standard`, `spot`, `backfill`), and latency (`p50Ms: 138`, `p95Ms: 285`).

### 2.6 GET & POST /v1/tokens (API Key Self-Service Manager)
- `GET /v1/tokens`: Lists active scoped keys with masked strings (`vf_live_••••••••3fa9`), allowed lanes, and RPS limits.
- `POST /v1/tokens`: Provisions a new cryptographic credential. Returns raw key strictly once.
- `DELETE /v1/tokens/:id`: Instantly revokes key and purges Redis cache in <1ms.

---

## 3. Legacy / Internal Sovereign Queue Endpoints

### 2.1 Video Generation (Google Veo 3.1)
Dispatch a 10s cinematic video generation task to the cluster.

- **Method**: `POST`
- **Path**: `/api/v1/generate/video`
- **Content-Type**: `application/json`

#### Request Body
```json
{
  "prompt": "Cinematic wide-angle shot of Elbsandsteingebirge rock towers rising above dawn mist, 8k resolution, golden hour light",
  "model": "veo-3.1-lite-lower-priority",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "start_frame": "/optional/path/or/base64/opening_frame.jpg",
  "async_mode": true
}
```

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `prompt` | string | Yes | - | Detailed description of the video to generate. |
| `model` | string | No | `veo-3.1-lite-lower-priority` | Model slug: `veo-3.1-lite-lower-priority` or `veo-3.1-pro`. |
| `aspect_ratio` | string | No | `16:9` | Target aspect ratio: `16:9` or `9:16`. |
| `resolution` | string | No | `1080p` | Video resolution: `720p` or `1080p`. |
| `start_frame` | string | No | `null` | Optional start image path, URL, or base64 for video continuation. |
| `async_mode` | boolean | No | `true` | When true, returns immediately with HTTP 202 and a `job_id`. |

#### Response (HTTP 202 Accepted)
```json
{
  "success": true,
  "job_id": "vf_job_8a7d2f41",
  "status": "processing",
  "estimated_seconds": 35
}
```

---

### 2.2 Image Generation (Nano Banana Pro 8K)
High-throughput photorealistic image generation for YouTube thumbnails and packaging.

- **Method**: `POST`
- **Path**: `/api/v1/generate/image`
- **Content-Type**: `application/json`

#### Request Body
```json
{
  "prompt": "Hyper-realistic YouTube thumbnail, shocked expression, high contrast lighting, 8k photorealism",
  "model": "nano-banana-pro",
  "aspect_ratio": "16:9",
  "output_count": 1
}
```

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `prompt` | string | Yes | - | Prompt describing the target image. |
| `model` | string | No | `nano-banana-pro` | Model: `nano-banana-pro` or `nano-banana-2`. |
| `aspect_ratio` | string | No | `16:9` | Image aspect ratio: `16:9`, `1:1`, `4:3`, `3:4`, or `9:16`. |
| `output_count` | integer | No | `1` | Number of image candidates (1-4). |

#### Response (HTTP 202 Accepted)
```json
{
  "success": true,
  "job_id": "img_job_5b19ef02",
  "status": "processing"
}
```

---

### 2.3 Neural Audio & Voiceover (48kHz)
High-definition speech synthesis and atmospheric Foley audio.

- **Method**: `POST`
- **Path**: `/api/v1/generate/audio`
- **Content-Type**: `application/json`

#### Request Body
```json
{
  "text": "Deep in the Saxon Switzerland canyons, sandstone monoliths pierce through the morning fog.",
  "voice_id": "george-documentary-warm",
  "speed": 1.0,
  "sample_rate": 48000
}
```

---

### 2.4 Autonomous Ebook Pipeline
Autonomous multi-chapter book compilation as a service.

- **Method**: `POST`
- **Path**: `/api/v1/generate/ebook`
- **Content-Type**: `application/json`

#### Request Body
```json
{
  "title": "The Sovereign Compute Playbook",
  "niche": "Technology & AI Infrastructure",
  "chapter_count": 10,
  "target_page_count": 220,
  "formats": ["epub", "pdf"]
}
```

---

### 2.5 Job Polling & Telemetry
Check status and retrieve download URLs for in-flight tasks.

- **Method**: `GET`
- **Path**: `/api/v1/jobs/{job_id}`

#### Response (HTTP 200 OK)
```json
{
  "success": true,
  "job": {
    "id": "vf_job_8a7d2f41",
    "status": "completed",
    "created_at": 1789151677356,
    "completed_at": 1789151712400,
    "duration_seconds": 35.04,
    "result": {
      "type": "video",
      "url": "https://avatarity.dev/media/videos/flow_output_8a7d2f41.mp4",
      "size_bytes": 10529269,
      "format": "mp4",
      "resolution": "1080p"
    }
  }
}
```

---

### 2.6 Batch Generation
Submit mixed atomic pipelines containing up to 5,000 video and image generations.

- **Method**: `POST`
- **Path**: `/api/v1/batch/generate`
- **Content-Type**: `application/json`

---

## 3. Client SDK Code Examples

### 3.1 cURL
```bash
curl -X POST https://avatarity.dev/api/v1/generate/video \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fast bird-like FPV drone diving through dramatic Elbsandsteingebirge mountain canyons",
    "model": "veo-3.1-lite-lower-priority",
    "aspect_ratio": "16:9",
    "resolution": "1080p"
  }'
```

### 3.2 Python
```python
import requests
import time

API_KEY = "vf_live_YOUR_API_KEY"
BASE_URL = "https://avatarity.dev"

# 1. Dispatch generation job
response = requests.post(
    f"{BASE_URL}/api/v1/generate/video",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "prompt": "Fast bird-like FPV drone diving through dramatic Elbsandsteingebirge mountain canyons",
        "model": "veo-3.1-lite-lower-priority",
        "aspect_ratio": "16:9"
    }
)
job = response.json()
job_id = job["job_id"]
print(f"Dispatched job: {job_id}")

# 2. Poll until complete
while True:
    res = requests.get(
        f"{BASE_URL}/api/v1/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    data = res.json()["job"]
    status = data["status"]
    if status == "completed":
        print("Video URL:", data["result"]["url"])
        break
    elif status == "failed":
        print("Failed:", data.get("error"))
        break
    time.sleep(3)
```

### 3.3 TypeScript
```typescript
import axios from 'axios';

const API_KEY = 'vf_live_YOUR_API_KEY';
const BASE_URL = 'https://avatarity.dev';

async function generateVideo() {
  const { data } = await axios.post(
    `${BASE_URL}/api/v1/generate/video`,
    {
      prompt: 'Fast bird-like FPV drone diving through dramatic Elbsandsteingebirge mountain canyons',
      model: 'veo-3.1-lite-lower-priority',
      aspect_ratio: '16:9',
    },
    {
      headers: { Authorization: `Bearer ${API_KEY}` },
    }
  );

  console.log(`Job queued: ${data.job_id}`);
}
```

---

## 4. Status Codes & Error Handling

| Code | Status | Meaning |
| :--- | :--- | :--- |
| `200` | OK | Request processed synchronously, or telemetry returned. |
| `202` | Accepted | Job enqueued successfully in the fleet cluster. |
| `400` | Bad Request | Missing prompt, invalid aspect ratio, or malformed JSON. |
| `401` | Unauthorized | Missing or expired Bearer token. |
| `409` | Conflict | Ambiguous submission state. Idempotency key protected. |
| `429` | Too Many Requests | Rate limit exceeded. Backoff recommended. |
| `500` | Gateway Error | Upstream provider error. Auto-fallback initiated. |