{ "openapi": "3.1.0", "info": { "title": "AERIOX Studio API", "version": "1.0.0", "description": "Programmatic access to AERIOX Studio's creative OS. Generate images,\nvideos, voice; train custom characters; apply prism presets;\nmanage wallet balance.\n\n**Audience priority:** MCP-native agents → indie developers → agencies → enterprise.\n\n**Authentication:** API keys (`Authorization: Bearer sk_live_*` or `x-api-key:` header).\nOAuth 2.0 PKCE flow available for end-user-facing apps.\n\n**Pricing:** USD-denominated PAYG wallet. `$5` free trial on first key,\n`$5` minimum top-up via Stripe. Every cost-bearing call is atomically\nreserved against the wallet before dispatch and refunded on provider failure.\n", "termsOfService": "https://create.aeriox.co/legal/terms", "contact": { "name": "AERIOX API", "url": "https://developer.aeriox.co", "email": "api@aeriox.co" }, "license": { "name": "Commercial", "url": "https://create.aeriox.co/legal/api-terms" } }, "servers": [ { "url": "https://api.aeriox.co", "description": "Production" }, { "url": "https://api-staging.aeriox.co", "description": "Staging (preview deploys)" } ], "security": [ { "apiKey": [] }, { "apiKeyHeader": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_*" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.aeriox.co/v1/oauth/authorize", "tokenUrl": "https://api.aeriox.co/v1/oauth/token", "scopes": { "generate": "Submit generation jobs", "read": "Read assets, characters, jobs, wallet", "admin": "Manage API keys + wallet config" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "examples": [ "insufficient_funds" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "Job": { "type": "object", "required": [ "job_id", "status", "type", "created_at" ], "properties": { "job_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "compose", "character_train", "prism_apply" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled", "nsfw_blocked" ] }, "progress_pct": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true }, "estimated_cost_usd": { "type": "number", "nullable": true }, "charged_cost_usd": { "type": "number", "nullable": true }, "output_urls": { "type": "array", "nullable": true, "items": { "type": "string", "format": "uri" } }, "error": { "allOf": [ { "$ref": "#/components/schemas/Error" } ], "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "prism_id": { "type": "string", "description": "Present only when `type=prism_apply`. Identifies the prism that was applied." } } }, "GenerateImageRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "examples": [ "fal-ai/flux/schnell" ] }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "negative_prompt": { "type": "string", "maxLength": 1000 }, "aspect_ratio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ] }, "resolution": { "type": "string", "examples": [ "1024x1024" ] }, "seed_image_url": { "type": "string", "format": "uri" }, "loras": { "type": "array", "maxItems": 8, "items": { "type": "object", "required": [ "path", "scale" ], "properties": { "path": { "type": "string", "format": "uri" }, "scale": { "type": "number", "minimum": 0, "maximum": 2 } } } }, "seed": { "type": "integer" }, "character_id": { "type": "string", "format": "uuid" }, "prism_id": { "type": "string" } } }, "GenerateVideoRequest": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "examples": [ "fal-ai/kling-3.0" ] }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "image_url": { "type": "string", "format": "uri" }, "duration_s": { "type": "integer", "minimum": 1, "maximum": 60 }, "with_audio": { "type": "boolean", "default": false }, "motion_id": { "type": "string" }, "character_id": { "type": "string", "format": "uuid" }, "prism_id": { "type": "string" } } }, "GenerateAudioRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "voice_id": { "type": "string" }, "character_voice_id": { "type": "string", "format": "uuid" }, "model": { "type": "string", "examples": [ "eleven_v3_multilingual" ] }, "phoneme_overrides": { "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } } } } }, "ComposeRequest": { "type": "object", "required": [ "segments" ], "properties": { "segments": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "asset_id", "start_time", "duration" ], "properties": { "asset_id": { "type": "string", "format": "uuid" }, "start_time": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "minimum": 0.1 }, "effects": { "type": "object", "additionalProperties": true } } } }, "output_resolution": { "type": "string", "default": "1080p" }, "output_format": { "type": "string", "enum": [ "mp4", "webm" ], "default": "mp4" } } }, "Character": { "type": "object", "required": [ "id", "name", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "training", "ready", "failed" ] }, "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "attributes": { "type": "object", "additionalProperties": true }, "voice_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ComposeJobAck": { "type": "object", "description": "Acknowledgement returned by `POST /v1/compose` when a stitch job has\nbeen queued. The job is asynchronous — clients poll\n`GET /v1/jobs/{id}` (with the `id` returned here) for terminal\nstatus and the stitched output URL.\n", "required": [ "id", "type", "status", "operation_id", "estimated_cost_usd_micros", "estimated_cost_usd", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Job id; pass to `GET /v1/jobs/{id}` to poll." }, "type": { "type": "string", "enum": [ "compose" ], "description": "Discriminator. Always `compose` for this endpoint." }, "status": { "type": "string", "enum": [ "queued" ], "description": "Initial status. The job advances to `running` and then a terminal state asynchronously." }, "operation_id": { "type": "string", "enum": [ "compose.stitch_per_minute" ], "description": "Cost-spine operation id used to price this job." }, "estimated_cost_usd_micros": { "type": "integer", "minimum": 0, "description": "Reserved wallet amount in USD micros (`1 USD = 1_000_000`)." }, "estimated_cost_usd": { "type": "number", "description": "Reserved wallet amount in USD (convenience field; equals `estimated_cost_usd_micros / 1_000_000`)." }, "created_at": { "type": "string", "format": "date-time" } } }, "Prism": { "type": "object", "required": [ "id", "name", "category", "compatible_with" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "compatible_with": { "type": "array", "items": { "type": "string", "enum": [ "image", "video", "audio" ] } }, "preview_url": { "type": "string", "format": "uri" } } }, "Model": { "type": "object", "required": [ "model_id", "type", "provider", "cost_usd_per_unit", "unit" ], "properties": { "model_id": { "type": "string" }, "type": { "type": "string", "enum": [ "image", "video", "audio", "compose", "training", "prism" ] }, "provider": { "type": "string" }, "max_resolution": { "type": "string", "nullable": true }, "max_duration_s": { "type": "integer", "nullable": true }, "supports_audio": { "type": "boolean" }, "cost_usd_per_unit": { "type": "number" }, "unit": { "type": "string" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InsufficientFunds": { "description": "Wallet balance too low for estimated cost", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found (or not visible to this workspace)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Concurrency cap or rate limit exceeded", "headers": { "retry-after": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "summary": "Fetch the AERIOX OpenAPI 3.1 spec as JSON", "description": "Returns the canonical OpenAPI 3.1 document for the AERIOX public API\nas JSON. The spec is also available as YAML at\n`docs/api/aeriox.openapi.yaml` in the source repo. Public — no\nauthentication required. Cached at the edge for one hour.\n", "tags": [ "Discovery" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "tags": [ "API Keys" ], "summary": "Get current API key + workspace", "description": "Returns the workspace and API key metadata for the calling key.", "responses": { "200": { "description": "Workspace + API key info", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "api_key" ], "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plan": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "api_key": { "type": "object", "properties": { "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "daily_spend_cap_usd": { "type": "number", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/api-keys/{id}/rotate": { "post": { "operationId": "rotateApiKey", "tags": [ "API Keys" ], "summary": "Rotate an API key", "description": "Issues a new key value for the given key id. The old key is scheduled\nfor expiry; the response includes the new plaintext (returned exactly\nonce) and the old key's expiry timestamp.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rotated key", "content": { "application/json": { "schema": { "type": "object", "required": [ "new_key", "new_key_id" ], "properties": { "new_key": { "type": "string" }, "new_key_id": { "type": "string", "format": "uuid" }, "old_expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Key already revoked or rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/wallet": { "get": { "operationId": "getWallet", "tags": [ "Wallet" ], "summary": "Get wallet balance and recent transactions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } } ], "responses": { "200": { "description": "Wallet snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "recent_transactions" ], "properties": { "balance": { "type": "object", "additionalProperties": true }, "recent_transactions": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/wallet/topup": { "post": { "operationId": "topUpWallet", "tags": [ "Wallet" ], "summary": "Create a Stripe PaymentIntent to credit the wallet", "description": "Creates a Stripe PaymentIntent against the workspace's saved customer.\nIf `payment_method_id` is provided, the intent is confirmed immediately\n(off-session); otherwise the `client_secret` is returned for the client\nto confirm via Stripe.js. Webhook credits the wallet on success.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_usd" ], "properties": { "amount_usd": { "type": "number", "minimum": 5, "maximum": 1000 }, "payment_method_id": { "type": "string", "minLength": 1, "maxLength": 120 } } } } } }, "responses": { "200": { "description": "PaymentIntent created", "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_intent_id", "status", "amount_usd" ], "properties": { "payment_intent_id": { "type": "string" }, "client_secret": { "type": "string", "nullable": true }, "status": { "type": "string" }, "amount_usd": { "type": "number" }, "next_action": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "400": { "description": "Workspace has no Stripe customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "description": "Stripe error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/wallet/auto-recharge": { "post": { "operationId": "configureAutoRecharge", "tags": [ "Wallet" ], "summary": "Configure or clear wallet auto-recharge", "description": "Configures auto-recharge thresholds for the workspace. When `enabled`\nis `false`, all auto-recharge fields are cleared. When `true`, the\nthreshold, top-up amount, and saved Stripe payment method are set.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "enum": [ false ] } } }, { "type": "object", "required": [ "enabled", "threshold_usd", "amount_usd", "stripe_payment_method_id" ], "properties": { "enabled": { "type": "boolean", "enum": [ true ] }, "threshold_usd": { "type": "number", "minimum": 1, "maximum": 100 }, "amount_usd": { "type": "number", "minimum": 5, "maximum": 500 }, "stripe_payment_method_id": { "type": "string", "minLength": 1, "maxLength": 120 } } } ] } } } }, "responses": { "200": { "description": "Auto-recharge configuration applied", "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "threshold_usd": { "type": "number" }, "amount_usd": { "type": "number" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "Update failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/credits": { "get": { "operationId": "getCredits", "tags": [ "Wallet" ], "summary": "(Deprecated) Get legacy credit balance", "description": "Legacy endpoint exposing the universal credit pool plus 24h spend stats.\nDeprecated — use `/v1/wallet` for USD wallet state.\n", "deprecated": true, "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "type": "object", "required": [ "plan", "credits" ], "properties": { "plan": { "type": "string" }, "credits": { "type": "object", "properties": { "balance": { "type": "number" }, "monthly_grant": { "type": "number" }, "purchased": { "type": "number" } } }, "image": { "type": "object", "additionalProperties": true }, "video": { "type": "object", "additionalProperties": true }, "api_key_24h_spend_usd": { "type": "number" }, "api_key_daily_cap_usd": { "type": "number", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/pricing": { "get": { "operationId": "getPricing", "tags": [ "Discovery" ], "summary": "Get USD price list for all operations", "description": "Public endpoint — no authentication required.", "security": [], "responses": { "200": { "description": "Rate card", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "micros_per_unit", "operations", "generated_at" ], "properties": { "currency": { "type": "string" }, "micros_per_unit": { "type": "integer" }, "operations": { "type": "array", "items": { "type": "object", "required": [ "operation_id", "model", "provider", "unit", "price_usd_micros", "price_usd" ], "properties": { "operation_id": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "unit": { "type": "string" }, "price_usd_micros": { "type": "integer" }, "price_usd": { "type": "number" }, "notes": { "type": "string", "nullable": true } } } }, "generated_at": { "type": "string", "format": "date-time" } } } } } }, "503": { "description": "Pricing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/estimate": { "post": { "operationId": "estimateGeneration", "tags": [ "Discovery" ], "summary": "Estimate cost and feasibility for a generation", "description": "Returns credit + USD cost, p95 wall-clock estimate, and a feasibility\ncheck (`would_succeed`) with structured `reasons_blocked`. Does not\ncommit funds or call upstream providers.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 }, "duration": { "type": "integer", "minimum": 1, "maximum": 60 } } } } } }, "responses": { "200": { "description": "Estimate result", "content": { "application/json": { "schema": { "type": "object", "required": [ "credits", "usd", "estimated_seconds", "model", "would_succeed", "reasons_blocked" ], "properties": { "credits": { "type": "number" }, "usd": { "type": "number" }, "estimated_seconds": { "type": "number" }, "model": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "would_succeed": { "type": "boolean" }, "reasons_blocked": { "type": "array", "items": { "type": "string", "enum": [ "unknown_model", "insufficient_credits", "circuit_open", "prompt_blocked", "spend_cap_exceeded" ] } }, "current_balance": { "type": "number" }, "spend_cap": { "type": "object", "additionalProperties": true, "nullable": true } } } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/images/generate": { "post": { "operationId": "generateImage", "tags": [ "Generation" ], "summary": "Generate an image", "description": "Canonical image generation endpoint. Returns a queued job; clients\npoll `/v1/generations/{id}` for status and asset URLs.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateImageRequest" } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid model or body (e.g. video model on image endpoint)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "422": { "description": "Prompt blocked or needs review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/videos/generate": { "post": { "operationId": "generateVideo", "tags": [ "Generation" ], "summary": "Generate a video", "description": "Canonical video generation endpoint. Returns a queued job; clients\npoll `/v1/generations/{id}` for status and asset URLs.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateVideoRequest" } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid model or body (e.g. image model on video endpoint)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "422": { "description": "Prompt blocked or needs review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/audio/generate": { "post": { "operationId": "generateAudio", "tags": [ "Generation" ], "summary": "Generate audio (text-to-speech)", "description": "Synthesize speech via ElevenLabs. Audio synthesis is fast enough\nto be sync — returns a completed job inline with the audio URL.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAudioRequest" } } } }, "responses": { "202": { "description": "Job completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "422": { "description": "Prompt blocked or needs review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/compose": { "post": { "operationId": "composeVideo", "tags": [ "Generation" ], "summary": "Stitch multiple assets into a single video", "description": "Multi-shot video composition. Takes asset references and segment\ntiming, returns a queued composition job that is dispatched to a\nVercel Sandbox microVM running ffmpeg. The 202 response carries\nthe job id (and the wallet reservation snapshot); poll\n`GET /v1/jobs/{id}` until the job reaches a terminal state\n(`completed` / `failed` / `cancelled`) — the stitched output URL\nappears in the polled job's `output_urls` field.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeRequest" } } } }, "responses": { "202": { "description": "Job queued. The compose stitch runs asynchronously inside a\nVercel Sandbox; resolve via `GET /v1/jobs/{id}`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComposeJobAck" } } } }, "400": { "description": "Validation error — malformed body, missing `segments`, or per-segment shape violation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/generate": { "post": { "operationId": "createGeneration", "tags": [ "Generation" ], "summary": "(Deprecated) Submit a generation job", "description": "Legacy generation endpoint. Deprecated alias of `/v1/images/generate`\n(and video equivalents). Returns a queued job; clients poll\n`/v1/generations/{id}`.\n", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model", "prompt" ], "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 4000 }, "negative_prompt": { "type": "string", "maxLength": 2000 }, "aspect_ratio": { "type": "string", "maxLength": 20 }, "resolution": { "type": "string", "maxLength": 20 }, "duration": { "type": "integer", "minimum": 1, "maximum": 60 }, "with_audio": { "type": "boolean" }, "seed_image_url": { "type": "string", "format": "uri", "maxLength": 2048 }, "loras": { "type": "array", "maxItems": 8, "items": { "type": "object", "required": [ "path", "scale" ], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 2048 }, "scale": { "type": "number", "minimum": 0, "maximum": 2 } } } } } } } } }, "responses": { "202": { "description": "Generation queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "generation_id", "status", "model" ], "properties": { "generation_id": { "type": "string", "format": "uuid", "nullable": true }, "provider_request_id": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "queued" ] }, "model": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video" ] }, "credits_charged": { "type": "number", "description": "Studio credit units charged (legacy display field; not USD; informational only for API-key callers)." }, "cost": { "type": "object", "properties": { "usd_micros": { "type": "integer" }, "usd": { "type": "number" } } }, "poll_url": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid model or body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Provider circuit open or pricing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/generations/{id}": { "get": { "operationId": "getGeneration", "tags": [ "Jobs" ], "summary": "(Deprecated) Poll generation status", "description": "Deprecated alias of `/v1/jobs/{id}`. Workspace-scoped.", "deprecated": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Generation row", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "model" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "success", "failed" ] }, "model": { "type": "string" }, "prompt": { "type": "string" }, "kind": { "type": "string", "nullable": true }, "credits_charged": { "type": "number", "nullable": true, "description": "Studio credit units charged (legacy display field; not USD; informational only for API-key callers)." }, "asset_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/nodes": { "get": { "operationId": "listNodes", "tags": [ "Generation" ], "summary": "List cards (legacy `nodes` alias)", "description": "Backward-compat alias for `/v1/cards`. Response is dual-emitted with\nboth `nodes` and `cards` keys referencing the same array. Sunsets\non 2026-10-22.\n", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string" } }, { "name": "globals_only", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "parent_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Card list (dual-emitted)", "content": { "application/json": { "schema": { "type": "object", "required": [ "nodes", "cards", "count", "limit", "offset" ], "properties": { "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "cards": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Unknown card type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createNode", "tags": [ "Generation" ], "summary": "Create a card (legacy `nodes` alias)", "description": "Backward-compat alias for `POST /v1/cards`. Request accepts either\n`card_type` or legacy `node_type`. Response includes both `node` and\n`card` fields referencing the same row.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "card_type": { "type": "string" }, "node_type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "attributes": { "type": "object", "additionalProperties": true }, "preview_url": { "type": "string", "format": "uri" }, "thumb_url": { "type": "string", "format": "uri" }, "parent_id": { "type": "string", "nullable": true }, "visibility_scopes": { "type": "array", "items": { "type": "string" } }, "edges": { "type": "array", "items": { "type": "object", "required": [ "edge_type" ], "properties": { "to_card_id": { "type": "string" }, "to_node_id": { "type": "string" }, "edge_type": { "type": "string" }, "attributes": { "type": "object", "additionalProperties": true } } } } } } } } }, "responses": { "201": { "description": "Card created", "content": { "application/json": { "schema": { "type": "object", "required": [ "card", "node" ], "properties": { "node": { "type": "object", "additionalProperties": true }, "card": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/nodes/{id}": { "get": { "operationId": "getNode", "tags": [ "Generation" ], "summary": "Get a single card with outgoing edges", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Node + edges", "content": { "application/json": { "schema": { "type": "object", "required": [ "node", "edges" ], "properties": { "node": { "type": "object", "additionalProperties": true }, "edges": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteNode", "tags": [ "Generation" ], "summary": "Soft-delete a card", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "soft_deleted" ], "properties": { "ok": { "type": "boolean" }, "soft_deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cards/search": { "get": { "operationId": "searchCards", "tags": [ "Generation" ], "summary": "Semantic search across the workspace card library", "description": "Voyage-embedding-backed similarity search over cards. Workspace-scoped.\nReturns 503 when `VOYAGE_API_KEY` is not configured on the deployment.\n", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "card_type", "in": "query", "schema": { "type": "string" } }, { "name": "min_similarity", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1, "default": 0 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "card_type", "name", "similarity", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "card_type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "preview_url": { "type": "string", "nullable": true }, "thumb_url": { "type": "string", "nullable": true }, "similarity": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "query_tokens": { "type": "integer" }, "query_doc_chars": { "type": "integer" } } } } } }, "400": { "description": "Missing or invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "Semantic search disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cards/{id}/render": { "get": { "operationId": "renderCard", "tags": [ "Generation" ], "summary": "Render a card's structured back-side payload", "description": "Returns the uniform `RenderedInputs` payload produced by the registered\nrenderer for the card's type — the same view the canvas executor uses\nwhen wiring this card to a downstream node.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Card + rendered inputs", "content": { "application/json": { "schema": { "type": "object", "required": [ "card", "rendered" ], "properties": { "card": { "type": "object", "additionalProperties": true }, "rendered": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "Missing card id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/characters": { "post": { "operationId": "createCharacter", "tags": [ "Characters" ], "summary": "Create + train a custom character from reference images", "description": "Creates a character card and queues a training job. Returns a Job\ndescriptor (status `queued`) plus the new `character_id`. Poll\n`/v1/jobs/{id}` for completion. Wallet is charged at the\n`char.train_soul` rate.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "image_urls" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "image_urls": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "format": "uri" } }, "attributes": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "202": { "description": "Training queued", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Job" }, { "type": "object", "properties": { "character_id": { "type": "string", "format": "uuid" } } } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "503": { "description": "Pricing unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listCharacters", "tags": [ "Characters" ], "summary": "List workspace characters (cursor-paginated)", "description": "Cursor-paginated list of characters in the calling workspace. Soft-deleted rows are excluded.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of characters", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Character" } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/characters/{id}": { "get": { "operationId": "getCharacter", "tags": [ "Characters" ], "summary": "Fetch a single character", "description": "Returns a single character. 404 (not 403) for cross-workspace ids so existence is never leaked.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Character detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Character" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCharacter", "tags": [ "Characters" ], "summary": "Soft-delete a character", "description": "Requires `admin` scope. Returns 204 with no body.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/prisms": { "get": { "operationId": "listPrisms", "tags": [ "Prisms" ], "summary": "Catalog of preset prisms", "description": "Static catalog of one-click creative recipes. Filter by category or compatible media type.", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "compatible_with", "in": "query", "schema": { "type": "string", "enum": [ "image", "video", "audio" ] } } ], "responses": { "200": { "description": "Prism catalog", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Prism" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/prisms/{id}/apply": { "post": { "operationId": "applyPrism", "tags": [ "Prisms" ], "summary": "Apply a prism to an asset or new generation", "description": "Queues prism execution. Returns the queued Job; poll `/v1/jobs/{id}`\nfor terminal state. Provide exactly one of `asset_id`, `image_params`,\n`video_params`.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "uuid" }, "image_params": { "$ref": "#/components/schemas/GenerateImageRequest" }, "video_params": { "$ref": "#/components/schemas/GenerateVideoRequest" } } } } } }, "responses": { "202": { "description": "Prism application queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientFunds" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/oauth/authorize": { "get": { "operationId": "oauthAuthorize", "summary": "Begin OAuth 2.0 PKCE authorization", "description": "Authorization endpoint for the PKCE-only flow. Validates the request\nand redirects the user-agent to the consent screen.\n", "tags": [ "API Keys" ], "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "scope", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to consent screen" }, "400": { "description": "Invalid request" } } } }, "/v1/oauth/token": { "post": { "operationId": "oauthToken", "summary": "Exchange authorization code or refresh token for an access token", "description": "Token endpoint. Accepts `authorization_code` (after PKCE) or\n`refresh_token` grants. Returns a JWT access token bound to the\ngranting workspace and the requested scopes.\n", "tags": [ "API Keys" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type", "client_id" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string" }, "refresh_token": { "type": "string" }, "client_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string", "nullable": true }, "scope": { "type": "string" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth/revoke": { "post": { "operationId": "oauthRevoke", "summary": "Revoke an OAuth access or refresh token", "description": "Idempotent revocation. Returns 200 whether or not the token was\npreviously valid (per RFC 7009).\n", "tags": [ "API Keys" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ] }, "client_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token revoked (idempotent)" } } } }, "/v1/oauth/jwks": { "get": { "operationId": "oauthJwks", "summary": "JSON Web Key Set for OAuth access token verification", "description": "Public JWKS used by clients/resource servers to verify access-token\nsignatures. Cached aggressively; rotated infrequently.\n", "tags": [ "API Keys" ], "security": [], "responses": { "200": { "description": "JWKS document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/jobs/{id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "Poll unified job status", "description": "Workspace-scoped read of a job's current state. Replaces `/v1/generations/{id}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "cancelJob", "tags": [ "Jobs" ], "summary": "Cancel a queued or running job", "description": "Refunds any wallet reservation held by the job. Returns the job\nin its new (cancelled) state. 409 if the job has already reached\na terminal state.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Job is already in a terminal state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models": { "get": { "operationId": "listModels", "tags": [ "Discovery" ], "summary": "Capability + price catalog for every supported model", "description": "Returns every active model in the cost spine with capabilities (max resolution, duration, audio support) and per-unit USD pricing.", "responses": { "200": { "description": "Model catalog", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "Pricing source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "tags": [ { "name": "Generation", "description": "Image, video, audio, composition" }, { "name": "Characters", "description": "Custom character training and reuse" }, { "name": "Prisms", "description": "Preset library application" }, { "name": "Jobs", "description": "Async job lifecycle" }, { "name": "Wallet", "description": "USD balance and transactions" }, { "name": "Discovery", "description": "Models, pricing" }, { "name": "API Keys", "description": "Key management" } ] }