{ "openapi": "3.1.0", "info": { "title": "AITOPIA REST API", "version": "1.0.0", "description": "Run AITOPIA models, edits and batches over HTTP. Submit calls return a request_id; poll GET /v1/requests/{request_id} (optionally with ?wait=N) or receive a signed webhook. Results are kept 30 days. Credit figures are estimates. The sandbox server takes test keys (aitk_test_...): same requests and validation, simulated results, no credits spent." }, "servers": [ { "url": "https://api-live.aitopia.ai", "description": "Live: real runs, credits are charged. Live keys (aitk_live_...)." }, { "url": "https://api-sandbox.aitopia.ai", "description": "Sandbox: simulated runs, nothing is charged. Test keys (aitk_test_...)." } ], "security": [ { "Key": [] } ], "paths": { "/v1/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This document (public, no key).", "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document" } } } }, "/v1/models": { "get": { "operationId": "listModels", "summary": "List models.", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Models page", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } }, "has_more": { "type": "boolean" }, "next_offset": { "type": [ "integer", "null" ] } } } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models/{model_id}": { "get": { "operationId": "getModelSchema", "summary": "Input schema and price of one model.", "parameters": [ { "name": "model_id", "in": "path", "required": true, "description": "Model id, for example google/nano-banana-2. Send the \"/\" as it is or encoded as %2F (generated clients encode it); both reach the same model.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Model schema", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "input_schema": { "type": [ "object", "null" ], "additionalProperties": true }, "price": { "$ref": "#/components/schemas/Price" } } } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MODEL_NOT_FOUND or NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "runModel", "summary": "Submit a model run. The body is the model input (see GET /v1/models/{model_id}).", "description": "Besides the model input, the body may carry webhook_url and asset_name.", "parameters": [ { "name": "model_id", "in": "path", "required": true, "description": "Model id, for example google/nano-banana-2. Send the \"/\" as it is or encoded as %2F (generated clients encode it); both reach the same model.", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "Long-poll up to N seconds (integer 0-60) for a terminal status.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } }, { "name": "dry_run", "in": "query", "required": false, "description": "true/1/yes returns a price estimate and runs nothing; false/0/no (or absent) runs. Anything else is a 400.", "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0", "no" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "Optional https URL (public host only) that receives the final result as a signed POST." }, "asset_name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Dry run estimate (dry_run=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "INSUFFICIENT_CREDITS, KEY_CREDIT_CAP_REACHED or OVER_BUDGET", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MODEL_NOT_FOUND or NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "PRICE_CHANGED, PRICE_UNKNOWN or PLAN_EXPIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "PLAN_INVALID, ASSET_UNREACHABLE or NOT_SUPPORTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "UPSTREAM_5XX, or UPSTREAM_UNCERTAIN (the run may have started: check the request_id in the body and your balance before retrying)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "MODEL_UNAVAILABLE, SERVER_RESTARTING or SESSION_UNAVAILABLE (retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "TIMEOUT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/edit": { "post": { "operationId": "editMedia", "summary": "Edit an asset from an instruction.", "parameters": [ { "name": "wait", "in": "query", "required": false, "description": "Long-poll up to N seconds (integer 0-60) for a terminal status.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } }, { "name": "dry_run", "in": "query", "required": false, "description": "true/1/yes returns a price estimate and runs nothing; false/0/no (or absent) runs. Anything else is a 400.", "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0", "no" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_url", "instruction" ], "properties": { "asset_url": { "type": "string", "format": "uri" }, "instruction": { "type": "string" }, "media_type": { "type": "string" }, "max_credits": { "type": "number" }, "plan_token": { "type": "string", "description": "From a dry run: run exactly that priced plan." }, "webhook_url": { "type": "string", "format": "uri", "description": "Optional https URL (public host only) that receives the final result as a signed POST." } } } } } }, "responses": { "200": { "description": "Dry run estimate (dry_run=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "INSUFFICIENT_CREDITS, KEY_CREDIT_CAP_REACHED or OVER_BUDGET", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "PRICE_CHANGED, PRICE_UNKNOWN or PLAN_EXPIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "PLAN_INVALID, ASSET_UNREACHABLE or NOT_SUPPORTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "UPSTREAM_5XX, or UPSTREAM_UNCERTAIN (the run may have started: check the request_id in the body and your balance before retrying)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "MODEL_UNAVAILABLE, SERVER_RESTARTING or SESSION_UNAVAILABLE (retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "TIMEOUT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/batch": { "post": { "operationId": "runBatch", "summary": "Submit 1 to 12 generations as one request.", "parameters": [ { "name": "wait", "in": "query", "required": false, "description": "Long-poll up to N seconds (integer 0-60) for a terminal status.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } }, { "name": "dry_run", "in": "query", "required": false, "description": "true/1/yes returns a price estimate and runs nothing; false/0/no (or absent) runs. Anything else is a 400.", "schema": { "type": "string", "enum": [ "true", "1", "yes", "false", "0", "no" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/BatchItem" } }, "webhook_url": { "type": "string", "format": "uri", "description": "Optional https URL (public host only) that receives the final result as a signed POST." } } } } } }, "responses": { "200": { "description": "Dry run estimate (dry_run=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DryRun" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "INSUFFICIENT_CREDITS, KEY_CREDIT_CAP_REACHED or OVER_BUDGET", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "PRICE_CHANGED, PRICE_UNKNOWN or PLAN_EXPIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "PLAN_INVALID, ASSET_UNREACHABLE or NOT_SUPPORTED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "UPSTREAM_5XX, or UPSTREAM_UNCERTAIN (the run may have started: check the request_id in the body and your balance before retrying)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "MODEL_UNAVAILABLE, SERVER_RESTARTING or SESSION_UNAVAILABLE (retryable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "TIMEOUT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/requests/{request_id}": { "get": { "operationId": "getRequest", "summary": "Status and result of a request (owner only).", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The request_id returned by a submit call.", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "Long-poll up to N seconds (integer 0-60) for a terminal status.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } } ], "responses": { "200": { "description": "Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MODEL_NOT_FOUND or NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/requests/{request_id}/status": { "get": { "operationId": "getRequestStatus", "summary": "Alias of GET /v1/requests/{request_id}.", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The request_id returned by a submit call.", "schema": { "type": "string" } }, { "name": "wait", "in": "query", "required": false, "description": "Long-poll up to N seconds (integer 0-60) for a terminal status.", "schema": { "type": "integer", "minimum": 0, "maximum": 60 } } ], "responses": { "200": { "description": "Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MODEL_NOT_FOUND or NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/requests/{request_id}/cancel": { "post": { "operationId": "cancelRequest", "summary": "Ask to cancel a request.", "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "The request_id returned by a submit call.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancel" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MODEL_NOT_FOUND or NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "UPSTREAM_5XX, or UPSTREAM_UNCERTAIN (the run may have started: check the request_id in the body and your balance before retrying)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account/balance": { "get": { "operationId": "getBalance", "summary": "Credit balance.", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": [ "number", "null" ] }, "unlimited": { "type": "boolean" }, "paid_credits": { "type": [ "number", "null" ] }, "daily_credits_remaining": { "type": [ "number", "null" ] }, "daily_allowance": { "type": [ "number", "null" ] }, "sandbox": { "type": "boolean", "description": "Only on api-sandbox: true. The fixed play balance; nothing is charged." } } } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads": { "post": { "operationId": "upload", "summary": "Host a file (base64 up to about 19 MB, or import from source_url).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content_base64": { "type": "string" }, "content_type": { "type": "string" }, "file_name": { "type": "string" }, "source_url": { "type": "string", "format": "uri", "description": "Use instead of content_base64." } } } } } }, "responses": { "200": { "description": "Hosted file", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "size": { "type": [ "number", "null" ] } } } } } }, "400": { "description": "INVALID_INPUT (with field), URL_NOT_ALLOWED, MODEL_REQUIRED, MODEL_KIND_MISMATCH, MODEL_NOT_ALLOWED, DUPLICATE_ITEM or INVALID_RUN_TOKEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "FILE_TOO_LARGE or INPUT_TOO_LARGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads/link": { "post": { "operationId": "createUploadLink", "summary": "Get a one-time upload URL for files up to 95 MB (PUT the bytes; the answer holds the file URL).", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string" }, "content_type": { "type": "string" } } } } } }, "responses": { "200": { "description": "Upload link", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_url": { "type": [ "string", "null" ] }, "file_url": { "type": "null" }, "expires_at": { "type": [ "string", "null" ] }, "max_bytes": { "type": [ "number", "null" ] } } } } } }, "401": { "description": "UNAUTHENTICATED (missing/invalid/revoked key) or KEY_SESSION_EXPIRED (sign in to aitopia.ai to reactivate the key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMIT, RUN_LIMITED or QUEUE_LIMIT_EXCEEDED (see retry_after_seconds and the Retry-After header)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "INTERNAL_ERROR (an unexpected server error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "requestFinished": { "post": { "summary": "Sent to your webhook_url when a request reaches a terminal status.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried for up to 24 hours." } } } } }, "components": { "securitySchemes": { "Key": { "type": "http", "scheme": "bearer", "bearerFormat": "aitk_live_... or aitk_test_...", "description": "Send \"Authorization: Key \" (Bearer is also accepted). Live keys work on the live server, test keys on the sandbox server. Create keys on your aitopia.ai profile." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field": { "type": "string" }, "retry_after_seconds": { "type": "number" } } }, "request_id": { "type": "string", "description": "Present when the request was recorded before it failed: check GET /v1/requests/{request_id} before retrying." } } }, "Price": { "type": [ "object", "null" ], "properties": { "credits": { "type": [ "number", "null" ] }, "min": { "type": "number" }, "max": { "type": "number" }, "per_second": { "type": "number" } } }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "price": { "$ref": "#/components/schemas/Price" }, "execution_mode": { "type": [ "string", "null" ] }, "recommended": { "type": "boolean" } } }, "Media": { "type": "object", "required": [ "url", "content_type" ], "properties": { "url": { "type": "string", "format": "uri" }, "content_type": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" }, "duration": { "type": "number" } } }, "Output": { "type": "object", "required": [ "images", "videos", "audio", "files" ], "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/Media" } }, "videos": { "type": "array", "items": { "$ref": "#/components/schemas/Media" } }, "audio": { "type": "array", "items": { "$ref": "#/components/schemas/Media" } }, "files": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "content_type": { "type": [ "string", "null" ] } } } } } }, "RequestStatus": { "type": "string", "enum": [ "queued", "running", "completed", "partial", "failed", "cancelled" ] }, "Item": { "type": "object", "required": [ "status", "output" ], "properties": { "index": { "type": "integer" }, "status": { "$ref": "#/components/schemas/RequestStatus" }, "output": { "$ref": "#/components/schemas/Output" }, "error": { "$ref": "#/components/schemas/Error/properties/error" }, "credits_estimated": { "type": [ "number", "null" ] } } }, "Request": { "type": "object", "required": [ "request_id", "status", "endpoint", "created_at", "completed_at", "credits_estimated", "output", "status_url", "result_url", "cancel_url" ], "properties": { "request_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/RequestStatus" }, "endpoint": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "credits_estimated": { "type": [ "number", "null" ] }, "output": { "$ref": "#/components/schemas/Output" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "error": { "$ref": "#/components/schemas/Error/properties/error" }, "aitopia_url": { "type": "string", "format": "uri" }, "status_url": { "type": "string", "format": "uri" }, "result_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" } } }, "DryRun": { "type": "object", "properties": { "dry_run": { "const": true }, "endpoint": { "type": "string" }, "credits_estimated": { "type": [ "number", "null" ] }, "affordable": { "type": [ "boolean", "null" ] }, "credits_available": { "type": [ "number", "string", "null" ] }, "complete": { "type": "boolean" }, "basis": { "type": "string" }, "plan_token": { "type": "string", "description": "edit only: send it to POST /v1/edit to run exactly this priced plan." }, "plan_token_expires_in_sec": { "type": "number" }, "items": { "type": "array", "items": { "type": "object" } } } }, "BatchItem": { "type": "object", "required": [ "kind", "prompt", "model_id" ], "properties": { "kind": { "type": "string" }, "prompt": { "type": "string" }, "model_id": { "type": "string" }, "input": { "type": "object", "additionalProperties": true }, "asset_name": { "type": "string" } } }, "Cancel": { "type": "object", "required": [ "request_id", "cancel" ], "properties": { "request_id": { "type": "string" }, "cancel": { "type": "string", "enum": [ "cancelled", "cancellation_requested", "cannot_cancel", "already_terminal" ] }, "will_be_charged": { "type": "boolean" } } }, "Webhook": { "description": "Body of the signed POST sent to webhook_url: the same object GET /v1/requests/{request_id} returns. Headers: X-AITOPIA-Signature: t=,v1=.\")>; X-AITOPIA-Request-Id (use it to dedupe). Retried for up to 24 hours.", "allOf": [ { "$ref": "#/components/schemas/Request" } ] } } } }