{"openapi":"3.1.0","info":{"title":"Viralance API","version":"1.0.0","description":"Generate AI videos, images, voiceovers and more with your Viralance credits. Same models, prices and moderation as viralance.com. Docs: https://viralance.com/developers","contact":{"url":"https://viralance.com/developers"}},"servers":[{"url":"https://viralance-mcp-70260648239.us-central1.run.app"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Videos"},{"name":"Images"},{"name":"Audio & 3D"},{"name":"Autopilot"},{"name":"Products"},{"name":"Prompts"},{"name":"Trends"},{"name":"Credits"},{"name":"Models"},{"name":"Webhooks"},{"name":"Meta"}],"paths":{"/v1/balance":{"get":{"operationId":"getBalance","tags":["Credits"],"summary":"Get credit balance","security":[{"bearerAuth":[]}],"x-required-scope":"credits:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credits/history":{"get":{"operationId":"getCreditHistory","tags":["Credits"],"summary":"List credit transactions (newest first)","security":[{"bearerAuth":[]}],"x-required-scope":"credits:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/models":{"get":{"operationId":"listModels","tags":["Models"],"summary":"List video/image models and their credit costs","description":"Every supported model with its modes and the exact credit cost per duration/resolution. Costs are identical to the web app.","security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","required":false,"description":"Filter","schema":{"type":"string","enum":["video","image","all"],"default":"all"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/videos":{"post":{"operationId":"createVideo","tags":["Videos"],"summary":"Generate a video","description":"Text-, image- or reference-to-video. Credits are charged when the job is accepted and refunded automatically if generation fails. Returns 202 with a video id; poll GET /v1/videos/{id} or pass callbackUrl.","security":[{"bearerAuth":[]}],"x-required-scope":"video:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","description":"Optional saved product ID from list_products. Groups this result with your product."},"prompt":{"type":"string","description":"The text prompt describing the video to generate"},"model":{"type":"string","description":"The AI model to use (e.g., veo3.1-fast, seedance-2.0, kling-3.0-pro)","enum":["veo3.1-fast","veo3-fast","seedance-2.0","seedance-2.5","kling-3.0-pro","kling-3.0-standard","kling-2.5-turbo-pro","kling-2.6-pro","kling-o3-pro","veo3.1-lite","hailuo-2.3","grok-imagine","grok-imagine-1.5","vidu-q3-turbo","wan-2.7","ltx-2-19b","hunyuan-1.5","pixverse-v5","happy-horse-1.1","pixverse-v6","minimax-h3"]},"duration":{"type":"number","description":"Video duration in seconds (4-30 depending on model)"},"resolution":{"type":"string","description":"Video resolution. Defaults to the model's own default tier (720p where it exists). MiniMax H3 uses 768p/2k/4k instead of 720p/1080p.","enum":["480p","540p","720p","768p","1080p","2k","4k"]},"mode":{"type":"string","description":"Generation mode","enum":["text-to-video","image-to-video","reference-to-video"]},"sourceImageUrl":{"type":"string","description":"Source image URL for image-to-video mode"},"referenceImageUrls":{"type":"array","items":{"type":"string"},"description":"Reference image URLs for reference-to-video mode (1-9; VEO 3.1 uses up to 3, Seedance up to 9, Kling uses the first as start frame + the rest as elements)."},"aspectRatio":{"type":"string","description":"Video aspect ratio","enum":["9:16","16:9","1:1"]},"callbackUrl":{"type":"string","format":"uri","description":"Optional https URL. A signed POST is sent when the job reaches a final state."}},"required":["prompt","model","duration"]}}}},"responses":{"202":{"description":"Accepted (job queued; poll or use callbackUrl)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"callbacks":{"completion":{"{$request.body#/callbackUrl}":{"post":{"summary":"Job reached a final state","parameters":[{"name":"Viralance-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>"},{"name":"Viralance-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Viralance-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried with backoff (6 attempts)."}}}}}}},"get":{"operationId":"listVideos","tags":["Videos"],"summary":"List videos (newest first)","security":[{"bearerAuth":[]}],"x-required-scope":"video:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","required":false,"description":"Filter by status","schema":{"type":"string","enum":["pending","processing","completed","failed"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedList"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/videos/{id}":{"get":{"operationId":"getVideo","tags":["Videos"],"summary":"Get a video (status, progress, URLs)","security":[{"bearerAuth":[]}],"x-required-scope":"video:read","parameters":[{"name":"id","in":"path","required":true,"description":"Video id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/edits":{"post":{"operationId":"createVideoEdit","tags":["Videos"],"summary":"Edit a video (reframe, upscale, subtitles, lip-sync, restyle, …)","description":"sourceVideoUrl must be a Viralance-hosted or fal.media URL. Per-second operations are priced from a server-side duration measurement. Most operations return 202 and a video id (poll or webhook); subtitle returns the finished video (201).","security":[{"bearerAuth":[]}],"x-required-scope":"video:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","description":"Optional saved product ID from list_products. Groups this result with your product."},"operation":{"type":"string","enum":["kling-edit","topaz","reframe","bg-remove","subtitle","motion","restyle","upscale","lipsync"]},"sourceVideoUrl":{"type":"string","description":"URL of the source video. Must be a Viralance-hosted video (from list_videos / get_video_status) or a fal.media URL."},"aspectRatio":{"type":"string","description":"For reframe (REQUIRED): one of 1:1, 16:9, 9:16, 4:3, 3:4, 21:9, 9:21"},"referenceImageUrl":{"type":"string","description":"For motion: the character image to animate"},"audioUrl":{"type":"string","description":"For lipsync (REQUIRED): the replacement audio track to sync lips to"},"consentAttested":{"type":"boolean","description":"For lipsync (REQUIRED): confirm you have the depicted person’s consent. Public figures are not permitted."},"prompt":{"type":"string","description":"For restyle (REQUIRED): describes the target style"},"styleStrength":{"type":"number","description":"For restyle: style strength 0-100 (default 50)"},"durationSeconds":{"type":"number","description":"Deprecated and ignored: the source duration is always measured server-side (reframe max 10s, upscale max 15s, restyle billed per minute, lipsync max 10 min). Videos whose duration cannot be measured are rejected."},"language":{"type":"string","description":"For subtitle: ISO language code (default en)"},"fontColor":{"type":"string","description":"For subtitle: caption text color (default white)"},"highlightColor":{"type":"string","description":"For subtitle: highlight color (default purple)"},"position":{"type":"string","enum":["top","center","bottom"],"description":"For subtitle: caption position"},"callbackUrl":{"type":"string","format":"uri","description":"Optional https URL. A signed POST is sent when the job reaches a final state."}},"required":["operation","sourceVideoUrl"]}}}},"responses":{"201":{"description":"Completed synchronously (e.g. subtitle)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"202":{"description":"Accepted (job queued; poll or use callbackUrl)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"callbacks":{"completion":{"{$request.body#/callbackUrl}":{"post":{"summary":"Job reached a final state","parameters":[{"name":"Viralance-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>"},{"name":"Viralance-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Viralance-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried with backoff (6 attempts)."}}}}}}}},"/v1/films":{"post":{"operationId":"composeFilm","tags":["Videos"],"summary":"Stitch clips (+ optional music) into one film","security":[{"bearerAuth":[]}],"x-required-scope":"video:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clips":{"type":"array","description":"Ordered clips to stitch back-to-back. Each: { url, durationSec }.","items":{"type":"object","properties":{"url":{"type":"string","description":"Public URL of the clip (e.g. a generate_video output)"},"durationSec":{"type":"number","description":"Seconds of this clip to include (2-15)"}},"required":["url","durationSec"]},"minItems":2,"maxItems":20},"musicUrl":{"type":"string","description":"Optional background music track URL"}},"required":["clips"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analyses":{"post":{"operationId":"analyzeVideo","tags":["Videos"],"summary":"Analyze a video (virality score or content analysis)","security":[{"bearerAuth":[]}],"x-required-scope":"video:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoUrl":{"type":"string","description":"URL of the video to analyze"},"mode":{"type":"string","enum":["virality","analysis"],"description":"Default virality"},"prompt":{"type":"string","description":"For analysis mode: a custom question about the video"}},"required":["videoUrl"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/images":{"post":{"operationId":"createImage","tags":["Images"],"summary":"Generate an image","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string","description":"Optional saved product ID from list_products. Groups this result with your product."},"prompt":{"type":"string","description":"The text prompt describing the image to generate"},"model":{"type":"string","description":"The AI model to use","enum":["bria-product","gpt-image-2.5","grok-image","nano-banana","gpt-image","nano-banana-pro","seedream"]},"aspectRatio":{"type":"string","description":"Image aspect ratio","enum":["9:16","1:1","16:9","4:5"]},"quality":{"type":"string","description":"Quality level (for GPT Image only)","enum":["low","medium","high"]},"resolution":{"type":"string","description":"Resolution (for Nano Banana Pro only)","enum":["1k","2k","4k"]},"referenceImageUrls":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Up to 4 reference image URLs for style/composition guidance (image-to-image). Bria Product Shot requires exactly one; GPT Image 2.5 accepts up to three; Nano Banana Pro and Seedream accept up to four. Use it to keep a consistent art style across many generations."},"outputFormat":{"type":"string","description":"Output encoding: png (lossless, best for sprites/cut-outs) or jpeg (default)","enum":["jpeg","png"]}},"required":["prompt","model"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listImages","tags":["Images"],"summary":"List images (newest first)","security":[{"bearerAuth":[]}],"x-required-scope":"image:read","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedList"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/images/edits":{"post":{"operationId":"createImageEdit","tags":["Images"],"summary":"Edit an image (background removal, outpaint)","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["bg-remove","outpaint"]},"sourceImageUrl":{"type":"string","description":"URL of the source image"},"expand":{"type":"number","description":"For outpaint (REQUIRED): pixels to expand on each side (50-700)"},"prompt":{"type":"string","description":"For outpaint: optional guidance for the new areas"}},"required":["operation","sourceImageUrl"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/images/try-on":{"post":{"operationId":"createVirtualTryOn","tags":["Images"],"summary":"Virtual try-on (person + garment)","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personImageUrl":{"type":"string","description":"URL of the person / model photo"},"garmentImageUrl":{"type":"string","description":"URL of the garment / clothing photo to put on the person"}},"required":["personImageUrl","garmentImageUrl"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/images/product-dimensions":{"post":{"operationId":"createProductDimensions","tags":["Images"],"summary":"Product dimension image","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string","description":"URL of the product photo (ideally on a plain/white background)"},"dimensions":{"type":"array","description":"One or more measurements to annotate","items":{"type":"object","properties":{"name":{"type":"string","enum":["height","width_bottom","width_top"]},"value":{"type":"number","description":"Measurement value (> 0)"},"unit":{"type":"string","enum":["mm","cm","m","in","ft"]},"position":{"type":"string","enum":["top","bottom","left","right"]}},"required":["name","value","unit"]}},"style":{"type":"string","enum":["default","childlike","elegant"],"description":"Visual style (default: default)"},"background":{"type":"string","description":"white, cream, charcoal, or a hex color (default: white)"},"title":{"type":"string","description":"Optional title text (max 80 chars)"}},"required":["imageUrl","dimensions"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/voiceovers":{"post":{"operationId":"createVoiceover","tags":["Audio & 3D"],"summary":"Text-to-speech voiceover","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The text to speak (max 5000 chars)"},"voice":{"type":"string","enum":["Aria","Roger","Sarah","Laura","Charlie","George","Callum","River","Liam","Charlotte","Alice","Matilda","Will","Jessica","Eric","Chris","Brian","Daniel","Lily","Bill","Rachel"],"description":"Voice name. Default Rachel"},"language":{"type":"string","description":"Optional ISO 639-1 language code"}},"required":["text"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/3d-models":{"post":{"operationId":"create3DModel","tags":["Audio & 3D"],"summary":"Image to 3D model (GLB)","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceImageUrl":{"type":"string","description":"URL of the source image"},"shouldTexture":{"type":"boolean","description":"Generate textures (default true)"}},"required":["sourceImageUrl"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products":{"get":{"operationId":"listProducts","tags":["Products"],"summary":"List saved products","security":[{"bearerAuth":[]}],"x-required-scope":"image:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"saveProduct","tags":["Products"],"summary":"Create or update a saved product (free)","security":[{"bearerAuth":[]}],"x-required-scope":"image:create","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":1000},"imageUrls":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":3},"scenePrompt":{"type":"string","maxLength":2000},"recipeId":{"type":"string","maxLength":40}},"required":["name","imageUrls"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/prompts/enhance":{"post":{"operationId":"enhancePrompt","tags":["Prompts"],"summary":"Optimize a prompt for a model","security":[{"bearerAuth":[]}],"x-required-scope":"prompt:use","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"The original prompt to enhance"},"type":{"type":"string","description":"Type of content being generated","enum":["video","image"]},"style":{"type":"string","description":"Desired visual style","enum":["cinematic","realistic","anime","3d","artistic","commercial"]},"count":{"type":"number","description":"Number of enhanced prompts to generate (1-5)"}},"required":["prompt"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/prompts/caption":{"post":{"operationId":"generateCaption","tags":["Prompts"],"summary":"Viral caption + hashtags","security":[{"bearerAuth":[]}],"x-required-scope":"prompt:use","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"videoDescription":{"type":"string","description":"Description of the video content"},"niche":{"type":"string","description":"Content niche/category","enum":["fashion","food","tech","travel","fitness","beauty","comedy","education","lifestyle","business"]},"tone":{"type":"string","description":"Desired caption tone","enum":["professional","casual","funny","inspirational","controversial"]},"includeEmojis":{"type":"boolean","description":"Whether to include emojis in the caption"}},"required":["videoDescription"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/prompts/hooks":{"post":{"operationId":"generateHooks","tags":["Prompts"],"summary":"Viral opening hooks","security":[{"bearerAuth":[]}],"x-required-scope":"prompt:use","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"topic":{"type":"string","description":"The video topic or main message"},"targetAudience":{"type":"string","description":"Target audience description"},"hookStyle":{"type":"string","description":"Style of hooks to generate","enum":["question","controversial","story","statistic","challenge"]},"count":{"type":"number","description":"Number of hooks to generate (1-5)"}},"required":["topic"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream model provider failed (credits were refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trends":{"get":{"operationId":"getTrends","tags":["Trends"],"summary":"Latest trends (returns locked:true until unlocked)","security":[{"bearerAuth":[]}],"x-required-scope":"trends:read","parameters":[{"name":"region","in":"query","required":false,"description":"Region","schema":{"type":"string","enum":["USA","UK","Europe","Australia","Asia"],"default":"USA"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trends/unlock":{"post":{"operationId":"unlockTrends","tags":["Trends"],"summary":"Unlock trends for 7 days (spends credits unless already active)","security":[{"bearerAuth":[]}],"x-required-scope":"trends:read","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/autopilot/runs":{"post":{"operationId":"createAutopilotRun","tags":["Autopilot"],"summary":"Start an autopilot run","description":"Plans, generates and verifies a set of assets from one brief. Pauses in awaiting_approval if the estimate exceeds your per-run credit cap.","security":[{"bearerAuth":[]}],"x-required-scope":"autopilot:use","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Natural language description of what you want to create"},"conversationId":{"type":"string","description":"Optional: continue an existing autopilot conversation"},"attachedImageUrl":{"type":"string","description":"Optional: source image URL for image-to-video / image editing"},"callbackUrl":{"type":"string","format":"uri","description":"Optional https URL. A signed POST is sent when the job reaches a final state."}},"required":["prompt"]}}}},"responses":{"202":{"description":"Accepted (job queued; poll or use callbackUrl)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"callbacks":{"completion":{"{$request.body#/callbackUrl}":{"post":{"summary":"Job reached a final state","parameters":[{"name":"Viralance-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>"},{"name":"Viralance-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"Viralance-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Acknowledged. Anything else is retried with backoff (6 attempts)."}}}}}}}},"/v1/autopilot/runs/{id}":{"get":{"operationId":"getAutopilotRun","tags":["Autopilot"],"summary":"Get an autopilot run (status, items, activity)","security":[{"bearerAuth":[]}],"x-required-scope":"autopilot:use","parameters":[{"name":"id","in":"path","required":true,"description":"Run id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/autopilot/runs/{id}/approve":{"post":{"operationId":"approveAutopilotRun","tags":["Autopilot"],"summary":"Approve (or reject) a run awaiting approval","security":[{"bearerAuth":[]}],"x-required-scope":"autopilot:use","parameters":[{"name":"id","in":"path","required":true,"description":"Run id","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"approve":{"type":"boolean","description":"true to approve (default), false to reject/cancel"},"selectedIndices":{"type":"array","items":{"type":"integer","minimum":0},"description":"Only run these plan items"}}}}}},"responses":{"202":{"description":"Accepted (job queued; poll or use callbackUrl)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"description":"Invalid request (validation error, bad JSON, bad Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Credential lacks the required scope, IP not allowed, or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A request with this Idempotency-Key is still in progress","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Idempotency-Key reused with a different request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit, daily per-key spend cap or concurrency limit","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error (generic message; details are logged server-side)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/secret":{"get":{"operationId":"getWebhookSecret","tags":["Webhooks"],"summary":"Get the webhook signing secret for this credential","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/secret/rotate":{"post":{"operationId":"rotateWebhookSecret","tags":["Webhooks"],"summary":"Rotate the webhook signing secret (the old one stops working immediately)","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Meta"],"summary":"This OpenAPI document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (vrl_...) from viralance.com/dashboard/mcp, or an OAuth access token."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique key (1-255 chars, A-Z a-z 0-9 _ - : .). Retries with the same key and body within 24 h return the original response and never charge twice.","schema":{"type":"string","maxLength":255}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["INSUFFICIENT_CREDITS"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"request_id":{"type":"string"}}}}},"Envelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string"},"webhook":{"type":"object","properties":{"url":{"type":"string"},"registered":{"type":"boolean"}}}}},"List":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"request_id":{"type":"string"}}},"PaginatedList":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":["integer","null"]},"has_more":{"type":"boolean"},"next_offset":{"type":["integer","null"]}}},"request_id":{"type":"string"}}},"WebhookEvent":{"type":"object","required":["id","type","created","data"],"properties":{"id":{"type":"string","description":"Stable per job — use it to de-duplicate retries"},"type":{"type":"string","examples":["video.completed","video.failed","autopilot_run.completed","autopilot_run.partial"]},"created":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}}}}}