{ "openapi": "3.1.0", "info": { "title": "PixZoo image and video API", "version": "1.0.0", "description": "Start at https://pixzoo.ai/openapi.md. Existing API uses both HTTP status and a JSON code: HTTP 200 with code -1 is an error. Submission is not idempotent. callbackUrl is not implemented." }, "servers": [ { "url": "https://pixzoo.ai" } ], "security": [ { "bearerAuth": [] } ], "externalDocs": { "url": "https://pixzoo.ai/openapi.md" }, "paths": { "/api/agent/device/": { "post": { "operationId": "startToolAuthorization", "security": [], "summary": "Start browser approval for an AI tool; does not grant access until the user approves.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "client_name" ], "additionalProperties": false, "properties": { "client_id": { "type": "string", "const": "pixzoo-agent" }, "client_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scope": { "type": "string", "const": "media:upload media:generate tasks:read" } } } }, "application/json": { "schema": { "type": "object", "required": [ "client_id", "client_name" ], "additionalProperties": false, "properties": { "client_id": { "type": "string", "const": "pixzoo-agent" }, "client_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scope": { "type": "string", "const": "media:upload media:generate tasks:read" } } } } } }, "responses": { "200": { "description": "Display verification_uri_complete and user_code; keep device_code secret. Poll only at interval, stop at expires_in.", "content": { "application/json": { "schema": { "type": "object", "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ], "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string", "format": "uri" }, "verification_uri_complete": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" } } } } } }, "400": { "description": "OAuth error (authorization_pending, slow_down, access_denied, expired_token, invalid_grant). No automatic retry of ambiguous token issuance/rotation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "OAuth error (authorization_pending, slow_down, access_denied, expired_token, invalid_grant). No automatic retry of ambiguous token issuance/rotation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "OAuth error (authorization_pending, slow_down, access_denied, expired_token, invalid_grant). No automatic retry of ambiguous token issuance/rotation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/agent/token/": { "post": { "operationId": "exchangeToolToken", "security": [], "summary": "Exchange approved device code or rotate a refresh token.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "required": [ "client_id", "grant_type" ], "properties": { "client_id": { "type": "string", "const": "pixzoo-agent" }, "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:device_code", "refresh_token" ] }, "device_code": { "type": "string" }, "refresh_token": { "type": "string" } }, "oneOf": [ { "required": [ "device_code" ], "properties": { "grant_type": { "const": "urn:ietf:params:oauth:grant-type:device_code" } }, "not": { "required": [ "refresh_token" ] } }, { "required": [ "refresh_token" ], "properties": { "grant_type": { "const": "refresh_token" } }, "not": { "required": [ "device_code" ] } } ] } }, "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "client_id", "grant_type" ], "properties": { "client_id": { "type": "string", "const": "pixzoo-agent" }, "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:device_code", "refresh_token" ] }, "device_code": { "type": "string" }, "refresh_token": { "type": "string" } }, "oneOf": [ { "required": [ "device_code" ], "properties": { "grant_type": { "const": "urn:ietf:params:oauth:grant-type:device_code" } }, "not": { "required": [ "refresh_token" ] } }, { "required": [ "refresh_token" ], "properties": { "grant_type": { "const": "refresh_token" } }, "not": { "required": [ "device_code" ] } } ] } } } }, "responses": { "200": { "description": "Store privately. Access is valid for 15 minutes. Refresh tokens rotate once, expire after 30 days idle, and have a 90-day grant ceiling. Reusing a consumed refresh token revokes the grant.", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "refresh_token", "refresh_expires_in", "scope" ], "properties": { "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "refresh_expires_in": { "type": "integer" }, "scope": { "const": "media:upload media:generate tasks:read" } } } } } }, "400": { "description": "OAuth error (authorization_pending, slow_down, access_denied, expired_token, invalid_grant). No automatic retry of ambiguous token issuance/rotation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "OAuth error (authorization_pending, slow_down, access_denied, expired_token, invalid_grant). No automatic retry of ambiguous token issuance/rotation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "503": { "description": "OAuth error (authorization_pending, slow_down, access_denied, expired_token, invalid_grant). No automatic retry of ambiguous token issuance/rotation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/ai/generate/": { "post": { "operationId": "generateMedia", "summary": "Submit one image or video generation task. Never automatically retry a submission.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationRequest" }, "examples": { "image": { "value": { "schemaVersion": 1, "mediaType": "image", "model": "nano-banana-2", "prompt": "A red panda reading a book, soft natural light", "scene": "text-to-image", "options": { "aspectRatio": "1:1" } } }, "video": { "value": { "schemaVersion": 1, "mediaType": "video", "model": "seedance-2.0", "prompt": "A red panda reading a book, slow camera dolly, soft natural light", "scene": "text-to-video", "options": { "aspectRatio": "16:9" } } } } } } }, "responses": { "200": { "description": "Inspect code: 0 means success; -1 is a business error, even on HTTP 200.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/generateResponse" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "400": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/ai/query/": { "post": { "operationId": "queryTask", "summary": "Query a task owned by this API key user. Poll every 10 seconds; this does not generate again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "responses": { "200": { "description": "Inspect code: 0 means success; -1 is a business error, even on HTTP 200.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/queryResponse" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "400": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/storage/presign/": { "post": { "operationId": "presignUpload", "summary": "Reserve an ordinary media upload. PUT original file bytes to the returned uploadUrl using only its returned headers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" }, "examples": { "file": { "value": { "filename": "reference.png", "contentType": "image/png", "size": 1024, "purpose": "media" } } } } } }, "responses": { "200": { "description": "Inspect code: 0 means success; -1 is a business error, even on HTTP 200.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/presignResponse" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "400": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/storage/complete/": { "post": { "operationId": "completeUpload", "summary": "Confirm an uploaded file and obtain its final URL. Idempotent for the same uploadId and owner.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadRequest" }, "examples": { "file": { "value": { "uploadId": "11111111-1111-4111-8111-111111111111" } } } } } }, "responses": { "200": { "description": "Inspect code: 0 means success; -1 is a business error, even on HTTP 200.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/completeResponse" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "400": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected or unavailable. Inspect the JSON envelope; do not automatically resubmit generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use a browser-authorized tool access token, or a developer key from PIXZOO_API_KEY. Keys allow uploads, generation/image processing, and querying the user’s own tasks only; they cannot purchase credits, change account settings, or manage keys. Generation spends existing credits. Never forward the key to storage or media hosts." } }, "schemas": { "GenerationRequest": { "type": "object", "required": [ "schemaVersion", "mediaType", "model", "prompt" ], "description": "CanonicalMediaRequest v1; choose only parameters supported by the selected model in /openapi/models.json. Local paths must be uploaded first. No provider or callbackUrl is needed.", "properties": { "schemaVersion": { "const": 1 }, "mediaType": { "enum": [ "image", "video" ] }, "model": { "type": "string", "enum": [ "gpt-image-2", "gpt-image-2.5-flare", "gpt-image-2.5-sunburst", "z-image-turbo", "seedream-5.0", "seedream-5.0-flash", "seedream-5.0-pro", "wan2.5-text-to-image", "qwen-image-edit-plus", "nano-banana-2", "nano-banana-2.1", "nano-banana-pro", "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini", "seedance-2.5", "veo3.1-fast-official", "veo3.1-quality-official", "veo3.1-fast", "veo3.1-quality", "kling-v3", "wan3.0-video", "grok-imagine-image", "grok-imagine-video", "gemini-omni-flash", "gpt-image-2-official", "nano-banana-2-official", "nano-banana-pro-official" ] }, "prompt": { "type": "string" }, "scene": { "enum": [ "text-to-image", "image-to-image", "text-to-video", "image-to-video" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "aspectRatio": { "type": "string" }, "resolution": { "type": "string" }, "quality": { "type": "string" }, "duration": { "type": "number" }, "referenceImages": { "type": "array", "items": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https?://" }, "role": { "enum": [ "firstFrame", "lastFrame", "reference" ] }, "sizeBytes": { "type": "integer", "minimum": 1 } } } }, "referenceVideos": { "type": "array", "items": { "type": "string", "format": "uri", "pattern": "^https?://" } }, "referenceAudios": { "type": "array", "items": { "type": "string", "format": "uri", "pattern": "^https?://" } }, "maskUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "negativePrompt": { "type": "string" }, "seed": { "type": "integer" }, "count": { "type": "integer", "minimum": 1 }, "speedMode": { "enum": [ "seed", "noseed" ] }, "outputFormat": { "type": "string" }, "outputCompression": { "type": "integer" }, "moderation": { "enum": [ "auto", "low" ] }, "background": { "enum": [ "auto", "transparent", "opaque" ] }, "referenceTaskType": { "enum": [ "auto", "reference", "edit", "extend" ] }, "webSearch": { "type": "boolean" }, "generateAudio": { "type": "boolean" }, "returnLastFrame": { "type": "boolean" }, "nsfwCheck": { "type": "boolean" }, "contentFilter": { "type": "boolean" }, "watermark": { "type": "boolean" }, "modelParams": { "type": "object", "additionalProperties": true }, "tools": { "type": "array", "items": {} } } } } }, "QueryRequest": { "type": "object", "required": [ "taskId" ], "properties": { "taskId": { "type": "string", "description": "The site data.id returned by generate, never an upstream taskId." } } }, "UploadRequest": { "type": "object", "required": [ "filename", "contentType", "size" ], "additionalProperties": false, "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif", "image/svg+xml", "video/mp4", "video/webm", "video/quicktime", "audio/mpeg", "audio/wav", "audio/x-wav", "audio/mp4", "audio/aac", "audio/ogg" ] }, "size": { "type": "integer", "minimum": 1, "description": "Actual original file size in bytes; enforce the contentType limit in /openapi/models.json uploadTypes." }, "purpose": { "const": "media", "default": "media", "description": "Ordinary reference upload; creates no material-library record." } } }, "CompleteUploadRequest": { "type": "object", "required": [ "uploadId" ], "additionalProperties": false, "properties": { "uploadId": { "type": "string", "format": "uuid" } } }, "generateResponse": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "const": 0 }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } } } }, "queryResponse": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "const": 0 }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "id", "mediaType", "status" ], "additionalProperties": true, "description": "Documented subset of the existing task record. Do not depend on internal/provider fields.", "properties": { "id": { "type": "string" }, "mediaType": { "enum": [ "image", "video" ] }, "status": { "enum": [ "queuing", "pending", "processing", "success", "failed", "canceled" ] }, "outputImages": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uri", "pattern": "^https?://" }, "description": "Original result media URLs for BOTH image and video tasks (legacy name)." }, "taskInfo": { "type": [ "string", "null" ], "description": "JSON string. If outputImages is empty, images[*].imageUrl holds original media URLs; use task mediaType to distinguish images and videos." } } } } }, "presignResponse": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "const": 0 }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "uploadId", "uploadUrl", "headers", "expiresAt" ], "properties": { "uploadId": { "type": "string" }, "uploadUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "completeResponse": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "const": 0 }, "message": { "type": "string" }, "data": { "type": "object", "required": [ "uploadId", "url", "filename", "size" ], "properties": { "uploadId": { "type": "string" }, "url": { "type": "string", "format": "uri", "pattern": "^https?://" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "materialId": { "type": [ "string", "null" ] } } } } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": -1 }, "message": { "type": "string" } } } } } }