AvatarityStudio
Get Started
DocumentationAPI Referencev1.0 OAS3

Avatarity Developer Platform

Wholesale programmatic access to Veo 3.1 video generation, Nano Banana Pro 8K packaging, high-speed execution, and autonomous fleet queue telemetry.

Access API Keys
Fleet Status: 100% Operational (18 Nodes Active)••Production Cluster: VPS 1 (65.108.6.149)•Underwritten by Axtrelis LLC
Base URL:https://avatarity.dev
Getting Started

Quickstart Guide

Start generating photorealistic Veo 3.1 videos and Nano Banana 8K assets in under 60 seconds with simple HTTP requests.

1

Get Bearer Key

Deposit a minimum of $10 or choose a compute tier on Pricing to mint your scoped key.

2

Submit Payload

Send an HTTP POST to /api/generate/video with your prompt and aspect ratio.

3

Receive Stream

Poll /api/jobs/:id or configure a webhook destination to receive finished MP4 binaries.

# 1. Dispatch your first generation job
curl -X POST https://avatarity.dev/api/generate/video \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Cinematic wide-angle drone shot skimming through sandstone mountain towers in Elbsandsteingebirge, dawn mist --ar 16:9",
    "model": "veo-3.1-lite-lower-priority",
    "aspectRatio": "16:9"
  }'
Security & Authorization

Authentication

The Avatarity Engine uses standard HTTP Bearer tokens. Pass your API key in the Authorization header of every request.

Standard Request Header Format:Non-expiring scoped key
Authorization: Bearer vf_live_YOUR_API_KEY
POST/v1/video/createPriority QoS Lanes

Dispatch Video Generation Job (Veo 3.1)

Initiates an asynchronous video synthesis job with multi-tier priority routing. Select your execution lane to balance turnaround latency and wholesale compute cost.

Priority Lane Pricing & SLA Matrix
Priority LaneWholesale CostTarget ETAPreemption & Concurrency SLA
turbo50 Units ($0.050)~14 secondsInstant 0ms queue bypass, dedicated high-throughput GPU pool.
standard30 Units ($0.030)~19-22 secondsStandard FIFO queue, guaranteed <20s dispatch SLA ($0.030 / video).
spot20 Units ($0.020)~45 secondsOpportunistic surplus capacity harvest; 50% wholesale discount.
backfillInternal Idle PoolPreemptibleAutonomous background maintenance grid. Yields instantly to paying traffic.
Request Payload (JSON Body)
FieldTypeRequiredDescription
promptstringRequiredCinematic scene description, camera angles, lighting, and action.
prioritystringOptionalPriority lane: "turbo", "standard", "spot", or "backfill". Defaults to "standard".
modelstringOptionalEngine target: "veo-3.1-lite", "veo3-fast", or "veo-3.1-pro".
aspect_ratiostringOptionalOutput ratio: "16:9" (Widescreen), "9:16" (Shorts/Reels), or "1:1". Defaults to "16:9".
durationnumberOptionalVideo duration in seconds (5 or 10). Defaults to 10.
webhook_urlstringOptionalHTTP(S) callback receiving HMAC-SHA256 signed event upon render completion.
curl -X POST https://avatarity.dev/v1/video/create \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite",
    "prompt": "Cinematic wide-angle drone shot skimming over dense mist-shrouded sandstone mountain spires, early morning golden light, 8k texture --ar 16:9",
    "priority": "turbo",
    "aspect_ratio": "16:9",
    "duration": 10
  }'
HTTP 202 Accepted Response Schema
{
  "task_id": "task_01j8x2k4m9v5q7y3",
  "status": "queued",
  "model": "veo-3.1-lite",
  "priority": "standard",
  "estimated_cost_units": 30,
  "estimated_cost_usd": 0.03,
  "eta_seconds": 14,
  "aspect_ratio": "16:9",
  "duration_seconds": 10,
  "created_at": "2026-09-30T16:00:00.000Z",
  "links": {
    "query": "/v1/video/query?task_id=task_01j8x2k4m9v5q7y3",
    "self": "/v1/video/create"
  }
}
GET/v1/video/query?task_id=...

Poll Video Status, Progress & Media URL

Queries task execution status, real-time progress bar percentage (0-100%), video player binary URL, and final actual compute cost deducted from your ledger.

curl -X GET "https://avatarity.dev/v1/video/query?task_id=task_01j8x2k4m9v5q7y3" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY"
HTTP 200 OK Response Schema (Succeeded)
{
  "task_id": "task_01j8x2k4m9v5q7y3",
  "status": "succeeded",
  "progress_pct": 100,
  "stage": "Rendering complete, sealed and delivered",
  "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,
  "fps": 60,
  "resolution": "1080p",
  "lane": "standard",
  "actual_cost_units": 30,
  "actual_cost_usd": 0.03,
  "completed_at": "2026-09-30T16:00:32.000Z",
  "error": null
}
POST/v1/images/generationsOpenAI SDK Compatible

Image Synthesis & High-CTR Thumbnails

Synthesize viral packaging and high-resolution assets formatted strictly to the OpenAI Image Generation specification. Drop-in compatible with standard OpenAI SDKs by updating the baseURL.

curl -X POST https://avatarity.dev/v1/images/generations \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "High CTR YouTube thumbnail: An ancient cybernetic monk meditating inside an obsidian datacenter vault, volumetric cyan lasers, hyper-detailed 8k resolution --ar 16:9",
    "n": 1,
    "size": "1792x1024",
    "response_format": "url"
  }'
HTTP 200 OK Response Schema
{
  "created": 1759248000,
  "data": [
    {
      "url": "https://avatarity.dev/images/thumbnails/thumb_megastructure_ringworld_shadow_squares_orbit.jpg",
      "revised_prompt": "High CTR YouTube thumbnail: An ancient cybernetic monk in obsidian datacenter vault..."
    }
  ]
}
GET/v1/models

Model Catalog, Capabilities & Spot Benchmarks

Lists active models with operational capabilities (text-to-video, image-to-video, unmetered-quota), hardware allocation targets, and live benchmark latency index.

curl -X GET "https://avatarity.dev/v1/models" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY"
GET/v1/healthLive Cluster Telemetry

Cluster Health, 100% Saturated Split & Latencies

Real-time telemetry reporting 100% permanent capacity saturation: external user demand vs Autonomous Backfill Engine surplus, 18 active worker nodes, queue depth per lane, and p50/p95 latency metrics.

curl -X GET "https://avatarity.dev/v1/health"
GET / POST/v1/tokens

Developer API Key Self-Service Manager

Programmatically provision, audit usage, and revoke scoped API keys. Raw tokens are generated cryptographically with format vf_live_[32 hex] and returned strictly once upon creation.

# 1. List active developer tokens
curl -X GET "https://avatarity.dev/v1/tokens" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY"

# 2. Mint new scoped developer API key
curl -X POST "https://avatarity.dev/v1/tokens" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Ingress Fleet",
    "allowed_lanes": ["turbo", "standard", "spot", "backfill"],
    "rate_limit_rps": 60,
    "expires_in": "90d"
  }'
POST/v1/avatar/create10-Slot Lifetime Quota

Register Custom Photo Avatar (Sticky Affinity)

Provisions a new custom photo portrait avatar onto the dedicated HeyGen backend account bound to your user profile. Deducts exactly 1 slot from your lifetime 10-avatar creation quota. Enforces sticky backend account affinity so all subsequent render jobs route deterministically to the node hosting your avatar.

Slot Allocation
10 Slots Lifetime

Permanent slots per user profile. No deletion permitted to prevent library churning and guarantee asset repeatability.

Account Affinity
Sticky Backend Binding

Pinned to dedicated HeyGen Business Plus accounts. Your avatars remain persistently available on your assigned node.

Credit Impact
0 Generative Credits

Operates through Avatar III & Talking Photo pipeline (0 generative credits depleted, unlimited plan minutes).

Request Payload (JSON Body)
FieldTypeRequiredDescription
photo_urlstringRequiredDirect HTTPS URL of the high-resolution portrait photograph (min 512x512, JPEG/PNG).
namestringRequiredHuman-readable label for the avatar (e.g. "Peggy Schuster").
source_typestringOptionalAvatar creation source: "custom_photo" (default) or "preconfigured".
base_avatar_namestringOptionalBase archetype to anchor expressions and pose (defaults to "priest").
look_namestringOptionalInitial look or style identifier (e.g. "executive", "casual").
voiceobjectOptionalDefault voice binding object: {"source": "fish_audio", "model": "s2.1-pro-free"}.
curl -X POST https://avatarity.dev/v1/avatar/create \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Peggy Schuster",
    "source_type": "custom_photo",
    "photo_url": "https://storage.schreinercontentsystems.com/avatars/peggy.jpg",
    "base_avatar_name": "priest",
    "look_name": "executive"
  }'
Response (HTTP 201 Created & HTTP 403 Quota Exceeded)
// 201 Created (Slot Allocated)
{
  "ok": true,
  "avatar": {
    "id": "av_usr_7x9q21",
    "user_id": "usr_9921",
    "name": "Peggy Schuster",
    "source_type": "custom_photo",
    "account_affinity": "heygen-primary",
    "created_at": "2026-10-04T19:40:00.000Z"
  },
  "quota": {
    "limit": 10,
    "used": 3,
    "remaining": 7
  }
}
// 403 Forbidden (Quota Exceeded)
{
  "error": "avatar_quota_exceeded",
  "message": "Custom avatar slot limit (10) reached for this profile. You cannot create more avatars.",
  "quota": {
    "limit": 10,
    "used": 10,
    "remaining": 0
  }
}
GET/v1/avatar/listCatalog & Quota Telemetry

List User Avatars & Quota Telemetry

Returns all custom photo avatars registered to the authenticated profile, preconfigured system archetypes (Priest, Sarah, Marcus), and current quota telemetry (slots used vs. 10-slot limit).

Query Parameters
ParameterTypeRequiredDescription
include_preconfiguredbooleanOptionalWhether to include system archetypes in the catalog. Defaults to true.
limitnumberOptionalMaximum number of avatars to return. Defaults to 50.
curl -X GET https://avatarity.dev/v1/avatar/list \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Response Body (HTTP 200 OK)
{
  "ok": true,
  "total": 6,
  "quota": {
    "limit": 10,
    "used": 3,
    "remaining": 7
  },
  "avatars": [
    {
      "id": "priest",
      "name": "Priest",
      "gender": "neutral",
      "type": "preconfigured",
      "looks": [
        "vestments",
        "casual"
      ],
      "default_look": "vestments",
      "preview_image_url": "https://assets.heygen.ai/avatar/priest_thumb.jpg",
      "account_affinity": "heygen-primary",
      "provisioning_status": "ready"
    },
    {
      "id": "av_usr_7x9q21",
      "name": "Peggy Schuster",
      "gender": "female",
      "type": "custom",
      "looks": [
        "executive"
      ],
      "default_look": "executive",
      "preview_image_url": "https://storage.schreinercontentsystems.com/avatars/peggy.jpg",
      "account_affinity": "heygen-primary",
      "provisioning_status": "ready"
    }
  ]
}
POST/v1/avatar/renderLane 4 Dispatch

Render 1080p Avatar Video (Avatar III Engine)

Submits an asynchronous talking-head video rendering task through the HeyGen-Utilizsator sovereign gateway (Lane 4). Renders strictly with Avatar III and Talking Photo models at 1080p Full HD resolution with watermarks stripped, depleting 0 generative credits on Business Plus.

Lane 4 Specification & Economics
Compute LaneWholesale CostOutput ResolutionGenerative CreditsExecution SLA
Lane 4 (HeyGen RPC)250 Units ($0.25 / min)1080p Full HD (1920x1080 / 1080x1920)0 Credits (Unlimited Plan)~45–75 seconds turnaround
Request Payload (JSON Body)
FieldTypeRequiredDescription
avatar_idstringRequiredArchetype ID ("priest") or custom avatar ID ("av_usr_7x9q21").
scriptstringRequiredSpeech transcript text for avatar synthesis and phoneme lip-sync.
titlestringOptionalOrganizational title for the render job.
audio_urlstringOptionalDirect HTTPS URL of external speech audio (Fish Audio, ElevenLabs, MP3/WAV).
voice_idstringOptionalHeyGen voice identifier if generating speech via native TTS.
aspect_ratiostringOptionalOutput frame: "16:9" (1920x1080) or "9:16" (1080x1920). Defaults to "16:9".
webhook_urlstringOptionalHTTPS callback destination receiving completion payload and MP4 download link.
curl -X POST https://avatarity.dev/v1/avatar/render \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "priest",
    "script": "Welcome to the Veo Forge masterclass on sovereign video pipelines.",
    "title": "Veo Forge Keynote #1",
    "aspect_ratio": "16:9"
  }'
Response Body (HTTP 202 Accepted)
{
  "id": "rend_41fa6b217b5d4c08baaa",
  "title": "Veo Forge Keynote #1",
  "status": "queued",
  "progress_percentage": 0,
  "current_stage": "opening_editor",
  "avatar": {
    "id": "priest",
    "name": "Priest"
  },
  "account_used": "heygen-primary",
  "credits_charged": 25,
  "created_at": "2026-10-04T19:42:00.000Z",
  "links": {
    "query": "/v1/avatar/query?id=rend_41fa6b217b5d4c08baaa"
  }
}
GET/v1/avatar/queryLive Telemetry

Poll Avatar Render Status & Download MP4

Queries the live progress percentage, stage milestone, and final 1080p MP4 binary link of an in-flight avatar render job. When completed, includes automated QA verification metrics (duration, resolution, byte size).

Query Parameters
ParameterTypeRequiredDescription
idstringRequiredRender job ID returned by /v1/avatar/render (e.g. "rend_41fa6b217b5d4c08baaa").
curl -X GET "https://avatarity.dev/v1/avatar/query?id=rend_41fa6b217b5d4c08baaa" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Response Schema (Processing vs. Completed)
// In-Flight Processing (68%)
{
  "id": "rend_41fa6b217b5d4c08baaa",
  "title": "Veo Forge Keynote #1",
  "status": "processing",
  "progress_percentage": 68,
  "current_stage": "rendering_68%",
  "created_at": "2026-10-04T19:42:00.000Z",
  "updated_at": "2026-10-04T19:43:12.000Z"
}
// 200 OK Completed (1080p Full HD)
{
  "id": "rend_41fa6b217b5d4c08baaa",
  "title": "Veo Forge Keynote #1",
  "status": "completed",
  "progress_percentage": 100,
  "current_stage": "completed",
  "download_url": "https://heygen.schreinercontentsystems.com/v1/jobs/rend_41fa6b217b5d4c08baaa/download",
  "qa_report": {
    "verified": true,
    "resolution": "1920x1080",
    "duration_seconds": 10.4,
    "size_bytes": 4128490
  }
}
MODEL 1.8Model 1.8 Sovereign 3D DiT

Internal Model 1.8: Expressiveness & Kinetic Tuning Levers

Fine-tune speech kinetic energy, facial posture, jaw openness, and micro-expressions for custom avatars. Powered by Axtrelis LLC's proprietary 14B parameter 3D Diffusion Transformer with 8-Step DMD Distillation running on sovereign NVIDIA A100 SXM4-80GB GPUs.

Subdued / Elderly0.55 – 0.75

Softens mouth openings and eliminates wild jaw drops. Produces dignified, gentle speech articulation ideal for grandmothers, serene hosts, or corporate leaders.

Neutral / Conversational0.90 – 1.20

Balanced natural head motion, realistic blink cadence, and organic lip sync calibrated against standard podcast or educational speech.

Dynamic / Theatrical1.75 – 2.50

Exaggerated phonetic mouth shapes, dramatic eyebrow accents, and high-energy gesticulation suitable for sales hooks, theatrical acting, or high-intensity shorts.

Expressiveness & Temporal Continuity Parameters
ParameterTypeDefaultPhysical Mechanism & Guidance
audio_guidance_scalefloat (0.5 – 2.5)1.0Controls acoustic sensitivity of mouth and jaw. Lower (0.6–0.75) for calm/elderly personas; higher (1.8+) for energetic speech.
text_guidance_scalefloat (1.0 – 3.0)1.0Classifier-Free Guidance (CFG). Higher values (1.5–2.2) enforce calm prompt styling against sudden acoustic transients.
num_cond_framesint (10 – 20)13 (0.52s)Autoregressive Video Continuation (AVC) temporal overlap. Seamlessly stitches multi-segment videos with zero boundary popping.
use_kv_cachebooleantrueRetains transformer cross-attention keys and values in GPU memory across segments to maintain continuous head trajectory.
enhance_hfbooleanfalseHigh-frequency facial texture preservation. Retains fine skin pores and eye reflections across long continuous sequences.
promptstring—Directs micro-expressions. E.g.: "An elderly grandmother speaking softly, subtle gentle lip articulation, peaceful steady gaze."
negative_promptstring—Negative constraint bounding. E.g.: "exaggerated facial expressions, wide open mouth, rapid head jerks, nodding, shaking."
curl -X POST https://avatarity.dev/v1/avatar/render \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-1.8",
    "image_url": "https://storage.schreinercontentsystems.com/avatars/marge_schneider.jpg",
    "audio_url": "https://storage.schreinercontentsystems.com/audio/speech_60s.mp3",
    "aspect_ratio": "16:9",
    "duration_seconds": 60,
    "audio_guidance_scale": 0.7,
    "text_guidance_scale": 1.5,
    "prompt": "An elderly grandmother speaking softly and gently, subtle calm lip movements, peaceful steady gaze, relaxed head posture.",
    "negative_prompt": "exaggerated facial expressions, wide open mouth, rapid head jerks, nodding, shaking, theatrical acting."
  }'
Verified Production Benchmark (NVIDIA A100 SXM4-80GB)
60.096s Audio Match

Full 60-second continuous avatar generation across 1,502 frames (19 auto-stitched AVC segments) matching speech audio to the millisecond. Zero VRAM memory leaks via PyTorch Native SDPA kernels and automatic GPU teardown on completion ($0.00/hr idle burn).

Stream Marge Schneider 60s (5.0 MB)Sample Segment 1 (598 KB)
PEFT / LORACharacter Adapter Fine-Tuning

Internal Model 1.8: Custom Persona LoRA Calibration

Train and dynamically load low-rank adaptation (LoRA) weights to lock character mannerisms, age-specific micro-gestures, and consistent identity anchors into Model 1.8's 3D DiT transformer.

Architectural Comparison: Internal Model 1.8 vs. HeyGen Avatar 3/4
FeatureInternal Model 1.8 (Sovereign 3D DiT)HeyGen Avatar 3 & 4 (Lane 4)
Pipeline ParadigmPure Multimodal 3D DiT DiffusionHybrid 3DMM Mesh + 2D Neural Warping
Source Input AssetAny single 2D photo (JPEG/PNG)2–5 minute 4K pre-recorded studio video
Persona CustomizationSupported via custom LoRA safetensorsLocked to proprietary studio actor pool
Sovereignty100% Sovereign Bare-Metal / Colab MeshCloud SaaS API dependency
Wholesale Cost$0.25 / min ($0.004167 / sec)$0.25 / min wholesale ($0.50 – $1.00 / min retail)
PEFT LoRA Training Blueprint & Dynamic Loading
// LoRA Configuration for Model 1.8 3D DiT Blocks (A100 80GB)
from peft import LoraConfig, get_peft_model

# 1. Target Linear Projections in Model 1.8 DiT Attention Layers
lora_config = LoraConfig(
    r=64,                            # LoRA Rank
    lora_alpha=32,                   # Scaling alpha
    target_modules=[
        "q_linear", "k_linear", "v_linear", 
        "proj", "cross_attn.q_linear", "cross_attn.kv_linear"
    ],
    lora_dropout=0.05,
    bias="none",
)

# 2. Dynamic Runtime Inference Injection
dit.load_lora("weights/loras/grandma_calm_persona.safetensors", "grandma", multiplier=0.75)
dit.enable_loras(["grandma"])
curl -X POST https://avatarity.dev/v1/avatar/render \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model-1.8",
    "image_url": "https://storage.schreinercontentsystems.com/avatars/marge_schneider.jpg",
    "audio_url": "https://storage.schreinercontentsystems.com/audio/speech_60s.mp3",
    "lora_adapter": "grandma_calm_v1",
    "lora_multiplier": 0.75,
    "audio_guidance_scale": 0.65
  }'
Sovereign Queue & Actress API

Sovereign Cluster Queue Architecture

High-throughput autonomous generation cluster deployed on VPS 1 (Helsinki), underwritten strictly by Axtrelis LLC. Features transparent hardware telemetry, dynamic worker allocation, and 16 parallel processing lanes.

Cluster Fleet
16 Streams
VPS 1 Helsinki
Median Latency
~34s
Per 10s Video
Throughput
4.8 / min
Locked 60 FPS
Wholesale Cost
30 Units ($0.030)
Veo 3.1 Sovereign (3¢/video)
Photoreal Actress & Avatar Presets
Elena Frost
Tech & Venture Breakdown
Crisp, authoritative delivery for software architecture & silicon teardowns.
ID: elena-frost
Marcus Vance
Investigative Intel
Deep cinematic baritone calibrated for declassified documents and geopolitics.
ID: marcus-vance
Chloe Chen
Modern Finance & Arbitrage
High-tempo breakdown specialist for liquidity pools and macro trading.
ID: chloe-chen
Sarah Jenkins
Ancient Megastructures
Hypnotic cadence for archaeology mysteries, astronomy, and deep sleep loops.
ID: sarah-jenkins
POST/api/queue

Dispatch Generation Job

Submits an asynchronous rendering job with an actress avatar, voiceover script, or cinematic scene to the sovereign queue. Allocates warm capacity slots without blocking the HTTP connection.

Request Payload (JSON Body)
FieldTypeRequiredDescription
promptstringRequiredMonologue or script with performance tags like [Pause 0.5s], [Emphasis], [Eye Lock].
actressIdstringOptionalAvatar profile: "elena-frost", "marcus-vance", "chloe-chen", or "sarah-jenkins". Defaults to "elena-frost".
actressNamestringOptionalHuman-readable persona label. Defaults to "Elena Frost".
aspectRatiostringOptionalOutput aspect ratio: "16:9" (YouTube/Desktop), "9:16" (Shorts/Reels), or "1:1". Defaults to "16:9".
modelstringOptionalEngine tier: "veo-3.1-lite-lower-priority" (unmetered quota) or "nano-banana-pro".
userIdstringOptionalTenant identifier to enable scoped personal queue queries.
voiceDeliverystringOptionalStyle: "conversational", "authoritative", "whisper", "dramatic", or "cadenced". Defaults to "conversational".
backgroundModestringOptionalRender backdrop: "obsidian-vault", "transparent-alpha" (for NLE overlay), "monochrome-minimal", or "custom-stage". Defaults to "obsidian-vault".
voicePacingnumberOptionalSpeech tempo multiplier from 0.8 to 1.3. Defaults to 1.0.
webhookUrlstringOptionalHTTP(S) endpoint to receive signed HMAC-SHA256 completion callback.
curl -X POST https://avatarity.dev/api/queue \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The macro economics of sovereign GPU infrastructure vs retail SaaS middleman margins. [Pause 0.5s] Why paying retail marks up compute by 1400%...",
    "actressId": "elena-frost",
    "actressName": "Elena Frost",
    "aspectRatio": "16:9",
    "model": "veo-3.1-lite-lower-priority",
    "userId": "usr_9a8b7c6d",
    "webhookUrl": "https://api.yourdomain.com/webhooks/avatarity"
  }'
HTTP 200 OK Response Schema
{
  "success": true,
  "job": {
    "id": "VF-8904",
    "userId": "usr_9a8b7c6d",
    "actressId": "elena-frost",
    "actressName": "Elena Frost",
    "prompt": "The macro economics of sovereign GPU infrastructure...",
    "aspectRatio": "16:9",
    "model": "veo-3.1-lite-lower-priority",
    "status": "queued",
    "queuePosition": 1,
    "estimatedSecondsRemaining": 28,
    "totalEstimatedSeconds": 28,
    "progressPercent": 2,
    "workerNode": "VPS-1-Node-01 (Helsinki)",
    "createdAt": 1727568000000,
    "durationSeconds": 10
  },
  "message": "Job VF-8904 successfully queued at position #1",
  "estimatedSeconds": 28
}
POST/api/queue (Batch Payload)

Batch Generation & Scene Sequencing

Enqueue multi-scene narrative arcs, episodic scripts, or chapter breakdowns into the sovereign queue in a single atomic request. Scenes execute in strict sequential timeline order, maintaining consistent actress styling and individual progress logs.

Background Modes (Alpha Transparency)
  • transparent-alpha: Renders with RGBA alpha channel for 1-click drag-and-drop overlay in Premiere, DaVinci, or Final Cut.
  • obsidian-vault: Deep studio dark aesthetic (#05070B) with edge rim lighting.
  • monochrome-minimal: High-contrast Swiss brutalist black-and-white grading.
  • custom-stage: Contextual volumetric stage lighting and environmental depth.
Voice Delivery & Pacing Profiles
  • conversational: Natural fluid cadence with human-like breathing pauses.
  • authoritative: Decisive, confident pitch for silicon teardowns and intelligence files.
  • whisper: Intimate, low-frequency resonance for mysteries and deep sleep loops.
  • dramatic: High-stakes emotional modulation for crime and investigative narratives.
# Enqueue a multi-scene episodic batch
curl -X POST https://avatarity.dev/api/queue \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_9a8b7c6d",
    "batchJobs": [
      {
        "prompt": "Hook: Why retail AI middlemen charge you 1400% markup on compute.",
        "actressId": "elena-frost",
        "voiceDelivery": "authoritative",
        "backgroundMode": "transparent-alpha",
        "aspectRatio": "16:9"
      },
      {
        "prompt": "Body: Sovereign infrastructure delivers raw compute at wholesale economics.",
        "actressId": "elena-frost",
        "voiceDelivery": "conversational",
        "backgroundMode": "obsidian-vault",
        "aspectRatio": "16:9"
      },
      {
        "prompt": "CTA: Connect to the Avatarity autonomous queue now.",
        "actressId": "elena-frost",
        "voiceDelivery": "dramatic",
        "backgroundMode": "monochrome-minimal",
        "aspectRatio": "16:9"
      }
    ]
  }'
GET/api/queue

Poll Queue Status & Cluster Telemetry

Query current cluster hardware capacity, in-flight job depth, countdown estimation, and finished MP4 binary download links.

# Query personal queue status
curl -X GET "https://avatarity.dev/api/queue?filter=personal&userId=usr_9a8b7c6d" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY"
DELETE/api/queue

Cancel In-Flight Queue Job

Cancels an in-flight or queued job, frees cluster stream capacity slots, and immediately recalculates queue positions for subsequent jobs.

# Cancel an in-flight or queued job
curl -X DELETE "https://avatarity.dev/api/queue?jobId=VF-8904" \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY"
GET/api/health

Fleet Health & 100% Capacity Telemetry

Real-time institutional telemetry reporting 100.0% continuous cluster capacity, dynamic split between external paying user demand and autonomous background workload balancing, priority burst gateway status, and SLA compliance metrics. Public endpoint requiring zero authorization.

# Query public fleet health & capacity split
curl -X GET "https://avatarity.dev/api/health"
Real-time Ingestion & Security

Webhook Callback Specification

Instead of maintaining long-lived HTTP polling sockets, provide a webhookUrl to receive real-time POST events upon job completion. Every webhook request is cryptographically signed using HMAC-SHA256.

Cryptographic Signature Header:HMAC-SHA256 Validated
X-VeoForge-Signature: hmac_sha256_3b68f921a9c4d2e8b0f1e7a6d5c4b3a2

Compute the SHA-256 HMAC of the raw request payload bytes using your webhook secret key, then verify against the header using constant-time comparison (crypto.timingSafeEqual or hmac.compare_digest).

POST/api/generate/video

Submit Video Generation Job (Veo 3.1)

Dispatches an asynchronous rendering job to the high-priority workhorse pool running Google Veo 3.1. Returns an immediate job identifier for polling or webhook dispatch.

Request Parameters (JSON Body)
FieldTypeRequiredDescription
promptstringRequiredDetailed text prompt describing motion, lighting, and camera drifts.
modelstringOptionalDefaults to "veo-3.1-lite-lower-priority" (unmetered quota).
aspectRatiostringOptionalOptions: "16:9" (default widescreen), "9:16" (Vertical Reels/Shorts), "1:1".
startFramestringOptionalPath, URL, or base64 image used as the opening frame to continue video action seamlessly.
asyncModebooleanOptionalDefaults to true. Queues job and returns immediately with jobId.
curl -X POST https://avatarity.dev/api/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 and sandstone rock pinnacles, 8k cinematic",
    "model": "veo-3.1-lite-lower-priority",
    "aspectRatio": "16:9"
  }'
POST/api/generate/image

Submit High-CTR Image / Thumbnail

Synthesize viral packaging assets using Nano Banana 2 (rapid unmetered ideation) or Nano Banana Pro (8K photorealistic widescreen render).

curl -X POST https://avatarity.dev/api/generate/image \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Dramatic aerial view of ancient sandstone towers shrouded in dawn fog, 8k octane render --ar 16:9",
    "model": "nano-banana-2",
    "aspectRatio": "16:9"
  }'
GET/api/jobs/:id

Poll Generation Job Status

Inspect real-time generation progress, queue latency, and binary media URL for an active jobId.

curl -X GET https://avatarity.dev/api/jobs/vf_job_8f29c1b7a4e0 \
  -H "Authorization: Bearer vf_live_YOUR_API_KEY"
Economics & Ledger

Quota & Compute Units

Avatarity operates on a transparent wholesale ledger. 1 Unit = $0.001 USD. Units never expire and rollover indefinitely across account lifetime.

Engine / ModelCompute RateQueue SLAExpiration Policy
Veo 3.1 Lite (Workhorse)30 Units ($0.030 / clip)~35s per 10s video (3¢ / video)Never Expire
Nano Banana 2.1 (Images)3 Units ($0.003 / render)4.8s per 1376x768 render (0.3¢ / image)Never Expire
Nano Banana Pro (8K)5 Units ($0.005 / render)High-CTR packaging (0.5¢ / image)Never Expire
HeyGen Avatar Engine (Lane 4)250 Units ($0.25 / min)1080p Full HD (25¢ / minute)Never Expire
Internal Model 1.8 Avatar250 Units ($0.25 / min = $0.004167/s)Sovereign 3D DiT Mesh (25¢ / minute)Never Expire
Throughput Governance

Rate Limits & Concurrency

Concurrency lanes determine how many rendering jobs run simultaneously. If you exceed your concurrency lane, jobs are placed in warm FIFO queues automatically without failing.

Starter Tier
1 Concurrent Lane

Up to 60 jobs queued in memory.

Creator Tier
2 Concurrent Lanes

Up to 300 jobs queued with priority dispatch.

Pro Tier
3 Concurrent Lanes

Dedicated warm account pool reservation.

Fault Tolerance

Gateway Errors & Resilience

Avatarity incorporates hardware circuit breakers that automatically recover from rate limits, cooldowns, and upstream UI shifts without client-side intervention.

Status CodeError CodeTrigger ConditionAutomated Engine Resolution
400 Bad RequestINVALID_PROMPTEmpty prompt or unsupported aspect ratioClient must update request body
401 UnauthorizedUNAUTHORIZEDMissing or malformed Bearer keyVerify token begins with vf_live_...
402 Payment RequiredQUOTA_EXCEEDEDLedger units balance is 0Deposit minimum $10 to refresh units ledger
429 Rate LimitedCONCURRENCY_LANE_CAPTenant concurrency lane fullEngine queues request or dispatches to warm standby pool
503 DegradedCIRCUIT_TRIPPEDUpstream model rate limit / maintenanceSovereign GPU fallback circuit activates automatically