{ "openapi": "3.1.0", "info": { "title": "Xide APP API", "version": "1.0.0", "description": "Generate images, videos, audio and edits with your Xide APP credits. Authenticate with `Authorization: Bearer xide_live_…` (or `X-API-Key`). Error messages follow the Accept-Language header (tr, en, es, ru, ar). An MCP server for AI assistants is available at /api/mcp.", "contact": { "name": "Xide APP", "url": "https://xide.app/dashboard/api" } }, "servers": [ { "url": "https://xide.app/api/v1" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Models", "description": "Catalog and exact pricing" }, { "name": "Generation", "description": "Start, follow and cancel jobs" }, { "name": "Files", "description": "Reference uploads and output downloads" }, { "name": "Account", "description": "Balance and key usage" } ], "paths": { "/models": { "get": { "operationId": "listModels", "tags": [ "Models" ], "summary": "List models", "description": "Requires the `read` scope.", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "image", "edit", "video", "audio", "lipsync", "icon", "utility", "recast" ] } }, { "name": "q", "in": "query", "description": "Search in model id and name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Models", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "models", "count" ], "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } }, "count": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/models/{model}": { "get": { "operationId": "getModel", "tags": [ "Models" ], "summary": "Get a model's inputs", "description": "Requires the `read` scope. Resolution variants have their own ids.", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" }, "example": "text-to-image-flux-2-pro" } ], "responses": { "200": { "description": "Model", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "model" ], "properties": { "model": { "$ref": "#/components/schemas/ModelDetail" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/quote": { "post": { "operationId": "quote", "tags": [ "Models" ], "summary": "Exact credit cost for inputs", "description": "Requires the `read` scope. The quoted amount is exactly what generate charges.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "model" ], "properties": { "model": { "type": "string" }, "inputs": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "model", "cost_credits", "balance" ], "properties": { "model": { "type": "string" }, "cost_credits": { "type": "integer" }, "balance": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "413": { "$ref": "#/components/responses/E413" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/generate/{model}": { "post": { "operationId": "generate", "tags": [ "Generation" ], "summary": "Start a generation", "description": "Requires the `generate` scope. Credits are reserved when the job is created and refunded if it fails. Repeats with the same Idempotency-Key within 24 hours return the original job (200, `Idempotent-Replayed: true`).", "parameters": [ { "name": "model", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,120}$" }, "example": "text-to-image-flux-2-pro" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,100}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "inputs" ], "properties": { "inputs": { "type": "object", "additionalProperties": true, "description": "Model inputs (see GET /models/{model})" }, "webhook_url": { "type": "string", "format": "uri", "description": "Public https URL notified when the job finishes" }, "metadata": { "description": "Echoed back on the job and webhook (max 4 KB)" } } } } } }, "responses": { "200": { "description": "Idempotent replay of an earlier job", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "job", "balance", "idempotent_replay" ], "properties": { "job": { "$ref": "#/components/schemas/Job" }, "balance": { "type": "integer" }, "idempotent_replay": { "type": "boolean" } } } } } } } }, "202": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "job", "balance" ], "properties": { "job": { "$ref": "#/components/schemas/Job" }, "balance": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "413": { "$ref": "#/components/responses/E413" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/jobs": { "get": { "operationId": "listJobs", "tags": [ "Generation" ], "summary": "List jobs (newest first)", "description": "Requires the `read` scope.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] } }, { "name": "cursor", "in": "query", "description": "next_cursor from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "jobs", "next_cursor" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/jobs/{job_id}": { "get": { "operationId": "getJob", "tags": [ "Generation" ], "summary": "Get a job", "description": "Requires the `read` scope. `wait` long-polls until the job finishes.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "wait", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/jobs/{job_id}/cancel": { "post": { "operationId": "cancelJob", "tags": [ "Generation" ], "summary": "Cancel a queued job", "description": "Requires the `generate` scope. Credits are refunded.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled job", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "job" ], "properties": { "job": { "anyOf": [ { "$ref": "#/components/schemas/Job" }, { "type": "null" } ] } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/uploads": { "post": { "operationId": "upload", "tags": [ "Files" ], "summary": "Upload a reference file", "description": "Requires the `upload` scope. Send a multipart `file` (max 1 GiB) or JSON `{ url }` (max 256 MB). Use the returned upload_id as a media input.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } }, "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "upload_id", "content_type", "size_bytes" ], "properties": { "upload_id": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "413": { "$ref": "#/components/responses/E413" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/files/{output_id}": { "get": { "operationId": "downloadFile", "tags": [ "Files" ], "summary": "Download an output", "description": "Requires the `read` scope. Redirects to a short-lived signed URL.", "parameters": [ { "name": "output_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "download", "in": "query", "schema": { "type": "integer", "enum": [ 0, 1 ] } } ], "responses": { "302": { "description": "Redirect to the file" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/account": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Balance, key info and today's usage", "description": "Requires the `account` scope.", "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "credits", "key", "usage_today" ], "properties": { "credits": { "type": "object", "required": [ "balance" ], "properties": { "balance": { "type": "integer" } } }, "key": { "type": "object", "required": [ "name", "prefix", "last4", "scopes", "rate_limit_per_min", "daily_credit_cap", "expires_at" ], "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "last4": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "generate", "read", "upload", "account" ] } }, "rate_limit_per_min": { "type": "integer" }, "daily_credit_cap": { "type": [ "integer", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "usage_today": { "type": "object", "required": [ "requests", "jobs", "credits_spent", "errors" ], "properties": { "requests": { "type": "integer" }, "jobs": { "type": "integer" }, "credits_spent": { "type": "integer" }, "errors": { "type": "integer" } } } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "xide_live_…" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "responses": { "E401": { "description": "Missing, invalid, revoked or expired API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "Not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Missing scope, suspended account, unverified email or IP not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Model, job or file not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict (job no longer cancellable, model disabled, or same Idempotency-Key in progress)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E413": { "description": "Body or file too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Rate limit, daily credit cap, concurrent uploads or active job limit reached (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Maintenance or developer API turned off (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "validation_error", "insufficient_credits", "rate_limited" ] }, "message": { "type": "string" }, "details": {} } } } }, "ModelSummary": { "type": "object", "required": [ "id", "name", "category", "description", "credits", "variants" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "image", "edit", "video", "audio", "lipsync", "icon", "utility", "recast" ] }, "description": { "type": "string" }, "credits": { "type": [ "object", "null" ], "required": [ "min", "max" ], "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } } }, "variants": { "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" } } } } } }, "ModelDetail": { "allOf": [ { "$ref": "#/components/schemas/ModelSummary" }, { "type": "object", "required": [ "inputs" ], "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/ModelInput" } } } } ] }, "ModelInput": { "type": "object", "required": [ "name", "label", "type", "required" ], "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "text", "number", "boolean", "enum", "image", "image_list", "video", "audio", "mask", "json" ] }, "required": { "type": "boolean" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": [ "string", "number" ] } }, "default": {}, "min": { "type": "number" }, "max": { "type": "number" }, "min_items": { "type": "integer" }, "max_items": { "type": "integer" }, "max_length": { "type": "integer" } } }, "JobOutput": { "type": "object", "required": [ "id", "kind", "url", "download_url", "content_type", "width", "height", "duration", "size_bytes", "nsfw" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "download_url": { "type": "string", "format": "uri" }, "content_type": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "duration": { "type": [ "number", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "nsfw": { "type": "boolean" } } }, "Job": { "type": "object", "required": [ "job_id", "status", "model", "model_name", "cost_credits", "created_at", "completed_at", "error", "outputs", "result", "metadata", "source" ], "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] }, "model": { "type": "string" }, "model_name": { "type": "string" }, "cost_credits": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/JobOutput" } }, "result": { "description": "Structured result for JSON-output tools" }, "metadata": {}, "source": { "type": "string", "enum": [ "api", "studio" ] } } } } } }