{ "openapi": "3.0.3", "info": { "title": "V4V Public API", "version": "1.1.0", "description": "Server-to-server LAB and Studio generation. See /developers for model-specific input discovery, media, callback verification, limits, and deployment." }, "servers": [ { "url": "https://v4v.ai/api/v1" } ], "security": [ { "ApiKey": [] } ], "paths": { "/models": { "get": { "operationId": "get_models", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models/{model}": { "get": { "operationId": "get_models_model", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/files/{id}": { "get": { "operationId": "get_files_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/tasks/{task_id}": { "get": { "operationId": "get_tasks_task_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/balance": { "get": { "operationId": "get_balance", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "number" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "operationId": "get_usage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "usage": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files": { "post": { "operationId": "uploadFile", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab": { "post": { "operationId": "submitLab", "description": "Validate inputs, reserve credits, then queue generation. Studio uses the selected dashboard workflow.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabGeneration" } } } }, "responses": { "202": { "description": "Generation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "callbacks": { "taskFinished": { "{$request.body#/callback_url}": { "post": { "security": [], "parameters": [ { "name": "X-V4V-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-V4V-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "object", "required": [ "event", "event_id" ], "properties": { "event": { "type": "string", "enum": [ "task.completed", "task.failed" ] }, "event_id": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Callback acknowledged" } } } } } } } }, "/studio": { "post": { "operationId": "submitStudio", "description": "Validate inputs, reserve credits, then queue generation. Studio uses the selected dashboard workflow.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioGeneration" } } } }, "responses": { "202": { "description": "Generation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "callbacks": { "taskFinished": { "{$request.body#/callback_url}": { "post": { "security": [], "parameters": [ { "name": "X-V4V-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-V4V-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "object", "required": [ "event", "event_id" ], "properties": { "event": { "type": "string", "enum": [ "task.completed", "task.failed" ] }, "event_id": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "Callback acknowledged" } } } } } } } }, "/studio/batches": { "post": { "operationId": "createStudioBatch", "summary": "Queue videos for 1–300 products", "description": "Requires an idempotency key and a maximum credit budget. Each item reserves credits only when admitted to start. Item settings override shared settings. Optional test_count=5 pauses after a sample. Ordinary generation has priority within the shared queue.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioBulkCreate" } } } }, "responses": { "202": { "description": "Batch accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioBulkBatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listStudioBatches", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "batches": { "type": "array", "items": { "type": "object", "properties": { "batch_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "max_credits": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" } } } }, "offset": { "type": "integer" }, "limit": { "type": "integer" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/studio/batches/{batch_id}": { "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^batch_[a-f0-9]{24}$" } } ], "get": { "operationId": "getStudioBatch", "description": "Read owned batch progress and item task results. Pagination is by zero-based item index. Poll at least five seconds apart.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioBulkBatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict or validation in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "controlStudioBatch", "description": "Control future starts with pause/resume/cancel, or create paid attempts with retry_failed, rework or restart. Restart reruns ALL items, including successes. Selected items must be terminal and have no unresolved generation requests. History and the cumulative credit budget are retained. Cancelled batches cannot resume but can explicitly restart/rework. Bodies are limited to 1 MiB.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioBulkControl" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioBulkBatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied or model disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, BATCH_CONFLICT, BATCH_ITEMS_ACTIVE, GENERATION_UNRESOLVED, NO_FAILED_ITEMS, BATCH_HISTORY_LIMIT or BATCH_CANCELLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input or media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "description": "Required for retry_failed, rework and restart (1–200 characters). Reuse the same key and identical body after a network interruption; changed content returns 409. Scoped to this account and batch.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "v4v_live_" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" } } } } }, "File": { "type": "object", "required": [ "id", "type", "content_type", "size" ], "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "type": { "type": "string", "enum": [ "image", "video", "audio" ] }, "content_type": { "type": "string" }, "size": { "type": "integer" } } }, "MediaReference": { "type": "string", "description": "External HTTP(S) URL or owned 24-character V4V file ID." }, "Model": { "type": "object", "required": [ "id", "name", "type", "enabled", "input_schema", "parameters_schema" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "chat" ] }, "enabled": { "type": "boolean" }, "input_schema": { "type": "object", "additionalProperties": true }, "parameters_schema": { "type": "object", "additionalProperties": true }, "pricing": { "type": "object", "description": "For chat: token rates, whole-credit rounding, minimum charge and initial reservation.", "additionalProperties": true }, "output_schema": { "type": "object", "additionalProperties": true } } }, "Generation": { "type": "object", "required": [ "input" ], "additionalProperties": false, "properties": { "model": { "type": "string", "description": "Required for LAB. ID or slug from model discovery." }, "input": { "type": "object", "additionalProperties": true }, "parameters": { "type": "object", "additionalProperties": true }, "callback_url": { "type": "string", "format": "uri" } } }, "Task": { "type": "object", "required": [ "task_id", "status", "credits_reserved", "created_at" ], "properties": { "task_id": { "type": "string", "pattern": "^task_[a-f0-9]{24}$" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] }, "source": { "type": "string", "enum": [ "lab", "studio" ] }, "model": { "type": "string" }, "credits_reserved": { "type": "number", "description": "Initially estimated credits; chat starts with 1 credit and expands the reservation to actual usage at settlement. Not a chat spending cap." }, "credits_used": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "project_name": { "type": "string", "description": "The project title chosen when the task was submitted." }, "batch_id": { "type": "string", "pattern": "^batch_[a-f0-9]{24}$" }, "item_index": { "type": "integer", "minimum": 0 }, "version": { "type": "integer", "minimum": 1 } } }, "Result": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "audio", "text" ] }, "url": { "type": "string", "format": "uri" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "text": { "type": "string", "description": "Inline chat answer; no download URL is required." }, "function_calls": { "type": "array", "description": "Function requests returned by chat; functions are not executed automatically.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "arguments": { "type": "string" }, "call_id": { "type": "string" } } } }, "incomplete": { "type": "boolean", "description": "True when chat reached its output token limit." }, "credits": { "type": "integer", "minimum": 1, "description": "Final chat charge rounded up to a whole credit." }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer", "minimum": 0 }, "uncached_input_tokens": { "type": "integer", "minimum": 0 }, "cached_input_tokens": { "type": "integer", "minimum": 0 }, "cache_write_tokens": { "type": "integer", "minimum": 0 }, "output_tokens": { "type": "integer", "minimum": 0 } } } } }, "LabGeneration": { "type": "object", "required": [ "model", "input" ], "additionalProperties": false, "properties": { "model": { "type": "string", "description": "Required for LAB. ID or slug from model discovery." }, "input": { "type": "object", "additionalProperties": true }, "parameters": { "type": "object", "additionalProperties": true }, "callback_url": { "type": "string", "format": "uri" }, "project_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Optional project title for LAB or Studio. Trimmed; must not be blank. Omit to use the default title." } } }, "StudioGeneration": { "type": "object", "required": [ "input" ], "additionalProperties": false, "properties": { "input": { "type": "object", "additionalProperties": false, "properties": { "prompt": { "type": "string", "maxLength": 10000 }, "product_name": { "type": "string", "maxLength": 10000 }, "product_description": { "type": "string", "maxLength": 10000 }, "product_images": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "reference_images": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "avatar_media": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "audio": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "video": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] } } }, "parameters": { "type": "object", "additionalProperties": false, "properties": { "duration": { "type": "integer", "minimum": 4, "maximum": 15, "description": "Selected workflow limits apply; OmniVid allows 4, 6, 8, 10." }, "aspect_ratio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "4:3", "3:4", "21:9", "adaptive" ] }, "quality": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ], "description": "Selected workflow limits apply." }, "avatar": { "type": "string", "nullable": true, "description": "Avatar image URL or owned file ID." }, "style": { "type": "string" }, "language": { "type": "string" }, "voice": { "type": "string" }, "placement": { "type": "string" } } }, "callback_url": { "type": "string", "format": "uri" }, "project_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Optional project title for LAB or Studio. Trimmed; must not be blank. Omit to use the default title." } } }, "StudioBulkItem": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 200 }, "product_id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "product_url": { "type": "string", "format": "uri", "maxLength": 8192 }, "input": { "type": "object", "additionalProperties": false, "properties": { "prompt": { "type": "string", "maxLength": 10000 }, "product_name": { "type": "string", "maxLength": 10000 }, "product_description": { "type": "string", "maxLength": 10000 }, "product_images": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "reference_images": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "avatar_media": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "audio": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "video": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] } } }, "parameters": { "type": "object", "additionalProperties": false, "properties": { "duration": { "type": "integer", "minimum": 4, "maximum": 15, "description": "Selected workflow limits apply; OmniVid allows 4, 6, 8, 10." }, "aspect_ratio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "4:3", "3:4", "21:9", "adaptive" ] }, "quality": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ], "description": "Selected workflow limits apply." }, "avatar": { "type": "string", "nullable": true, "description": "Avatar image URL or owned file ID." }, "style": { "type": "string" }, "language": { "type": "string" }, "voice": { "type": "string" }, "placement": { "type": "string" } } } }, "additionalProperties": false }, "StudioBulkCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "max_credits": { "type": "number", "exclusiveMinimum": true, "minimum": 0 }, "test_count": { "type": "integer", "enum": [ 5 ] }, "input": { "type": "object", "additionalProperties": false, "properties": { "prompt": { "type": "string", "maxLength": 10000 }, "product_name": { "type": "string", "maxLength": 10000 }, "product_description": { "type": "string", "maxLength": 10000 }, "product_images": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "reference_images": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "avatar_media": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "audio": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] }, "video": { "oneOf": [ { "$ref": "#/components/schemas/MediaReference" }, { "type": "array", "items": { "$ref": "#/components/schemas/MediaReference" } } ] } } }, "parameters": { "type": "object", "additionalProperties": false, "properties": { "duration": { "type": "integer", "minimum": 4, "maximum": 15, "description": "Selected workflow limits apply; OmniVid allows 4, 6, 8, 10." }, "aspect_ratio": { "type": "string", "enum": [ "9:16", "16:9", "1:1", "4:5", "4:3", "3:4", "21:9", "adaptive" ] }, "quality": { "type": "string", "enum": [ "360p", "480p", "720p", "1080p", "4k" ], "description": "Selected workflow limits apply." }, "avatar": { "type": "string", "nullable": true, "description": "Avatar image URL or owned file ID." }, "style": { "type": "string" }, "language": { "type": "string" }, "voice": { "type": "string" }, "placement": { "type": "string" } } }, "items": { "type": "array", "minItems": 1, "maxItems": 300, "items": { "$ref": "#/components/schemas/StudioBulkItem" } }, "callback_url": { "type": "string", "format": "uri", "maxLength": 8192, "description": "Optional public receiver for signed batch.updated, batch.completed, batch.paused and batch.cancelled events. Not a browser chat wakeup mechanism." } }, "required": [ "name", "max_credits", "items" ], "additionalProperties": false }, "StudioBulkBatch": { "type": "object", "properties": { "batch_id": { "type": "string", "pattern": "^batch_[a-f0-9]{24}$" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused", "cancelled", "completed" ] }, "waiting_reason": { "type": "string", "nullable": true }, "total_items": { "type": "integer" }, "test_count": { "type": "integer" }, "max_credits": { "type": "number" }, "credits_used": { "type": "number", "description": "Credits spent across ALL attempt versions." }, "credits_committed": { "type": "number", "description": "All historical spending plus current reservations; bounded by max_credits." }, "counts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Counts of the latest intended version per item, including queued and waiting_for_sample items. Earlier terminal attempts do not complete a new version." }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "sku": { "type": "string", "nullable": true }, "product_url": { "type": "string", "nullable": true }, "status": { "type": "string" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "version": { "type": "integer", "minimum": 1, "description": "Latest intended attempt version. New tasks may appear on the next worker tick. Version numbers increase but can skip values." }, "task_id": { "type": "string", "nullable": true, "description": "Task for the current intended version; null until the worker creates it." }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Only the current version results. Empty immediately after rework; old results stay in attempts history." }, "error": { "type": "object", "nullable": true, "additionalProperties": true } } } }, "state_token": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Meaningful batch state cursor; unchanged by renewed download URLs." }, "monitoring": { "type": "object", "properties": { "wait_tool": { "type": "string", "enum": [ "wait_studio_batch" ] }, "callback_enabled": { "type": "boolean" }, "automatic_chat_wakeup": { "type": "boolean", "enum": [ false ] } } } }, "required": [ "batch_id", "name", "status", "total_items", "max_credits", "items" ] }, "StudioBulkControl": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "cancel" ] }, "max_credits": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Optional increase to the cumulative budget; prior spending and active reservations still count." } } }, { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "retry_failed" ] }, "max_credits": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Optional increase to the cumulative budget; prior spending and active reservations still count." }, "input": { "type": "object", "additionalProperties": true }, "parameters": { "type": "object", "additionalProperties": true }, "item_indexes": { "type": "array", "minItems": 1, "maxItems": 300, "uniqueItems": true, "items": { "type": "integer", "minimum": 0, "maximum": 299 }, "description": "Only latest failed items may be selected. Omit to retry all failed items." } } }, { "type": "object", "additionalProperties": false, "required": [ "action", "items" ], "properties": { "action": { "type": "string", "enum": [ "rework" ] }, "max_credits": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Optional increase to the cumulative budget; prior spending and active reservations still count." }, "input": { "type": "object", "additionalProperties": true }, "parameters": { "type": "object", "additionalProperties": true }, "items": { "type": "array", "minItems": 1, "maxItems": 300, "items": { "type": "object", "additionalProperties": false, "properties": { "index": { "type": "integer", "minimum": 0, "maximum": 299 }, "product_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "product_url": { "type": "string", "minLength": 1, "maxLength": 8192 }, "input": { "type": "object", "additionalProperties": true }, "parameters": { "type": "object", "additionalProperties": true }, "task_id": { "type": "string", "pattern": "^task_[a-fA-F0-9]{24}$", "description": "Current task ID from this batch. Older replaced versions return BATCH_ITEM_VERSION_CHANGED." } }, "description": "Choose exactly one of index or current task_id. Optional changes override the previous request.", "oneOf": [ { "required": [ "index" ], "not": { "required": [ "task_id" ] } }, { "required": [ "task_id" ], "not": { "required": [ "index" ] } } ] } } } }, { "type": "object", "additionalProperties": false, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "restart" ] }, "max_credits": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Optional increase to the cumulative budget; prior spending and active reservations still count." }, "input": { "type": "object", "additionalProperties": true }, "parameters": { "type": "object", "additionalProperties": true } } } ], "discriminator": { "propertyName": "action" } } } } }