{ "openapi": "3.0.3", "info": { "title": "Qubrid Image API", "version": "1.1.0", "description": "Generate images from text prompts using advanced AI models with full parameter support." }, "servers": [ { "url": "https://platform.qubrid.com/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "schemas": { "ImageGenerationRequest": { "type": "object", "required": ["model", "prompt"], "properties": { "model": { "type": "string", "example": "qwen-image", "description": "The image generation model to use." }, "prompt": { "type": "string", "example": "A futuristic city skyline at sunset", "description": "The text prompt describing the image to generate." }, "enhance_prompt": { "type": "boolean", "default": false, "description": "Whether to automatically enhance the prompt before generation." }, "go_fast": { "type": "boolean", "default": true, "description": "Whether to prioritize faster generation." }, "guidance": { "type": "number", "default": 3, "description": "Guidance scale controlling prompt adherence." }, "negative_prompt": { "type": "string", "default": "", "description": "Elements you want to avoid in the generated image." }, "num_inference_steps": { "type": "integer", "default": 30, "description": "Number of denoising steps used during generation." }, "seed": { "type": "integer", "nullable": true, "default": null, "description": "Optional random seed for reproducible results." }, "disable_safety_checker": { "type": "boolean", "default": false, "description": "Disable the safety checker for generation." }, "image": { "type": "string", "nullable": true, "default": null, "description": "Optional input image for image-to-image generation or editing." }, "strength": { "type": "number", "default": 0, "description": "Strength of transformation when using an input image." }, "lora_weights": { "type": "string", "nullable": true, "default": null, "description": "Optional LoRA weights identifier." }, "lora_scale": { "type": "number", "default": 1, "description": "Scale factor for the primary LoRA weights." }, "extra_lora_weights": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Additional LoRA weights to apply." }, "extra_lora_scale": { "type": "array", "items": { "type": "number" }, "default": [1, 1], "description": "Scale values for additional LoRA weights." }, "aspect_ratio": { "type": "string", "example": "16:9", "description": "Aspect ratio for the generated image." }, "image_size": { "type": "string", "example": "optimize_for_quality", "description": "Controls image resolution or optimization mode." }, "output_format": { "type": "string", "example": "webp", "description": "Desired output image format." }, "output_quality": { "type": "integer", "default": 80, "description": "Compression quality for the output image." } } }, "ImageGenerationResponse": { "type": "object", "properties": { "created": { "type": "integer", "example": 1710000000, "description": "Unix timestamp when the image was generated." }, "data": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "nullable": true, "example": "https://cdn.qubrid.com/generated/image.webp", "description": "URL of the generated image." }, "b64_json": { "type": "string", "nullable": true, "example": "/9j/4AAQSkZJRgAB...", "description": "Base64-encoded image output when requested." } } } } } }, "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Missing required parameter: 'prompt'." }, "type": { "type": "string", "example": "invalid_request_error", "description": "Machine-readable error category." }, "code": { "type": "string", "example": "invalid_request", "description": "Specific machine-readable error code." }, "param": { "type": "string", "nullable": true, "example": "prompt", "description": "The request field that caused the error, or null." }, "request_id": { "type": "string", "example": "req-qubrid-abc123", "description": "Unique request identifier for debugging and support." } } } } }, "ModelNotFoundErrorResponse": { "type": "object", "description": "Returned when the specified image generation model does not exist or is not available.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "The model 'qwen-image-ultra' does not exist or is not available." }, "type": { "type": "string", "example": "invalid_request_error" }, "code": { "type": "string", "example": "model_not_found" }, "param": { "type": "string", "nullable": true, "example": "model" }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "InsufficientQuotaErrorResponse": { "type": "object", "description": "Returned when the account does not have enough credits to complete the request.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Insufficient credits to process this request. Please recharge your account." }, "type": { "type": "string", "example": "insufficient_quota" }, "code": { "type": "string", "example": "insufficient_quota" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "RateLimitErrorResponse": { "type": "object", "description": "Returned when request rate limits are exceeded.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Rate limit exceeded. Please try again later." }, "type": { "type": "string", "example": "rate_limit_error" }, "code": { "type": "string", "example": "rate_limit_exceeded" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "AuthenticationErrorResponse": { "type": "object", "description": "Returned when authentication fails.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Missing authentication credentials." }, "type": { "type": "string", "example": "authentication_error" }, "code": { "type": "string", "example": "missing_api_key" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "PermissionErrorResponse": { "type": "object", "description": "Returned when the authenticated account does not have permission to access the resource.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Permission denied: You do not have permission to access this model." }, "type": { "type": "string", "example": "permission_error" }, "code": { "type": "string", "example": "insufficient_quota" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "ServerErrorResponse": { "type": "object", "description": "Returned when an internal server error occurs.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "An unexpected error occurred while processing the request." }, "type": { "type": "string", "example": "server_error" }, "code": { "type": "string", "example": "internal_error" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "BackendUnavailableErrorResponse": { "type": "object", "description": "Returned when the upstream image provider is temporarily unavailable or could not be reached.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "The backend service is temporarily unavailable." }, "type": { "type": "string", "example": "server_error" }, "code": { "type": "string", "example": "backend_unavailable" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } }, "GatewayTimeoutErrorResponse": { "type": "object", "description": "Returned when the upstream image provider took too long to respond.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "The request timed out while waiting for the backend service." }, "type": { "type": "string", "example": "server_error" }, "code": { "type": "string", "example": "backend_error" }, "param": { "type": "string", "nullable": true, "example": null }, "request_id": { "type": "string", "example": "req-qubrid-abc123" } } } } } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/images/generations": { "post": { "summary": "Create Image", "description": "Generate an image with minimal or advanced parameters.", "operationId": "createImage", "tags": ["Images"], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" }, "examples": { "Minimal": { "summary": "Minimal request", "value": { "model": "qwen-image", "prompt": "A futuristic city skyline at sunset" } }, "Full": { "summary": "Full request with all parameters", "value": { "model": "qwen-image", "prompt": "A cyberpunk city street with neon reflections, flying cars overhead", "enhance_prompt": false, "go_fast": true, "guidance": 3, "negative_prompt": "", "num_inference_steps": 30, "seed": null, "disable_safety_checker": false, "image": null, "strength": 0, "lora_weights": null, "lora_scale": 1, "extra_lora_weights": [], "extra_lora_scale": [1, 1], "aspect_ratio": "16:9", "image_size": "optimize_for_quality", "output_format": "webp", "output_quality": 80 } } } } } }, "responses": { "200": { "description": "Image generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationResponse" }, "example": { "created": 1710000000, "data": [ { "url": "https://cdn.qubrid.com/generated/image.webp" } ] } } } }, "400": { "description": "Bad request - missing required fields, invalid values, or malformed input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationErrorResponse" } } } }, "402": { "description": "Insufficient credits to process the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientQuotaErrorResponse" } } } }, "403": { "description": "Forbidden - authenticated but not allowed to access this model or resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionErrorResponse" } } } }, "404": { "description": "Model not found - the specified image model does not exist or is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelNotFoundErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorResponse" } } } }, "502": { "description": "Bad gateway - upstream image provider is unavailable or returned an error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendUnavailableErrorResponse" } } } }, "504": { "description": "Gateway timeout - upstream image provider took too long to respond", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTimeoutErrorResponse" } } } } } } } } }