{ "openapi": "3.0.3", "info": { "title": "Qubrid OCR API", "version": "1.0.0", "description": "Extract and recognize text from images using OCR-specialized vision models through the OpenAI-compatible chat completions API." }, "servers": [ { "url": "https://platform.qubrid.com/v1" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "schemas": { "OCRRequest": { "type": "object", "required": ["model", "messages"], "properties": { "model": { "type": "string", "example": "Hunyuan/Hunyuan-OCR-1B", "description": "The OCR-specialized vision model to use for text extraction." }, "messages": { "type": "array", "description": "Chat-style input containing text instructions and image content for OCR processing.", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "user" }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "text" }, "text": { "type": "string", "example": "Extract all text from this image and preserve the layout structure." }, "image_url": { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/document.png", "description": "Publicly accessible image URL containing text to extract." } } } } } } } } }, "max_tokens": { "type": "integer", "default": 8192, "description": "Maximum number of tokens to generate in the OCR response." }, "temperature": { "type": "number", "default": 0.1, "description": "Sampling temperature for text extraction (lower = more deterministic)." }, "top_p": { "type": "number", "default": 1, "description": "Nucleus sampling parameter for OCR output." }, "stream": { "type": "boolean", "default": false, "description": "Whether to stream OCR output incrementally." } } }, "OCRResponse": { "type": "object", "description": "Standard OpenAI-compatible chat completion response with extracted text.", "properties": { "id": { "type": "string", "example": "chatcmpl-ocr-123456" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer", "example": 1710000000 }, "model": { "type": "string", "example": "Hunyuan/Hunyuan-OCR-1B" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "example": 0 }, "message": { "type": "object", "properties": { "role": { "type": "string", "example": "assistant" }, "content": { "type": "string", "example": "Header: Important Document\n\nSection 1: Introduction\nThis document contains important information...\n\nSection 2: Details\nKey points and data extracted from the image..." } } }, "finish_reason": { "type": "string", "example": "stop" } } } } } }, "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Missing required parameter: 'messages'." }, "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": "messages", "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 OCR 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 'ocr-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" } } } } }, "ContextLengthExceededErrorResponse": { "type": "object", "description": "Returned when the input exceeds the model's maximum context window.", "required": ["error"], "properties": { "error": { "type": "object", "required": ["message", "type", "code", "request_id"], "properties": { "message": { "type": "string", "example": "Context length exceeded: The input exceeds the model's maximum context length." }, "type": { "type": "string", "example": "invalid_request_error" }, "code": { "type": "string", "example": "context_length_exceeded" }, "param": { "type": "string", "nullable": true, "example": "messages" }, "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 OCR 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 OCR 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": { "/chat/completions": { "post": { "summary": "Extract Text from Images with OCR", "description": "Use specialized OCR vision models to extract and recognize text from images via the OpenAI-compatible chat completions API.", "operationId": "createOCRCompletion", "tags": ["OCR"], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCRRequest" }, "examples": { "Basic OCR": { "summary": "Extract text from a document image", "value": { "model": "Hunyuan/Hunyuan-OCR-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Extract all text from this image and preserve the layout structure." }, { "type": "image_url", "image_url": { "url": "https://example.com/document.png" } } ] } ], "max_tokens": 8192, "temperature": 0.1, "top_p": 1, "stream": false } }, "OCR with Layout": { "summary": "Extract text preserving document layout and structure", "value": { "model": "Hunyuan/Hunyuan-OCR-1B", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Extract all text from this document image while preserving the original layout, structure, and formatting." }, { "type": "image_url", "image_url": { "url": "https://example.com/form.jpg" } } ] } ], "max_tokens": 8192, "temperature": 0.05, "stream": false } } } } } }, "responses": { "200": { "description": "OCR text extraction completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OCRResponse" }, "example": { "id": "chatcmpl-ocr-123456", "object": "chat.completion", "created": 1710000000, "model": "Hunyuan/Hunyuan-OCR-1B", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "INVOICE #2024-001\nDate: March 30, 2024\n\nBilled To:\nJohn Smith\n123 Main Street\nNew York, NY 10001\n\nItems:\n1. Service A - $100.00\n2. Service B - $250.00\n\nTotal: $350.00" }, "finish_reason": "stop" } ] } } } }, "400": { "description": "Bad request - missing required fields, invalid values, or malformed JSON", "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 OCR model does not exist or is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelNotFoundErrorResponse" } } } }, "413": { "description": "Payload too large - input exceeds the model context window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextLengthExceededErrorResponse" } } } }, "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 OCR provider is unavailable or returned an error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendUnavailableErrorResponse" } } } }, "504": { "description": "Gateway timeout - upstream OCR provider took too long to respond", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayTimeoutErrorResponse" } } } } } } } } }