> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.qubrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze Image

> Analyze and understand images using multimodal vision-language models.



## OpenAPI

````yaml /vision/openapi.json POST /chat/completions
openapi: 3.0.3
info:
  title: Qubrid Vision API
  version: 1.0.0
  description: >-
    Analyze and understand images using multimodal vision-language models
    through the OpenAI-compatible chat completions API.
servers:
  - url: https://platform.qubrid.com/v1
security:
  - BearerAuth: []
paths:
  /chat/completions:
    post:
      tags:
        - Vision
      summary: Analyze Images with Vision Models
      description: >-
        Use a multimodal vision-language model to understand and describe images
        via the OpenAI-compatible chat completions API.
      operationId: createVisionCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisionRequest'
            examples:
              Basic Vision:
                summary: Analyze an image with a text prompt
                value:
                  model: Qwen/Qwen3-VL-Plus
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: What is in this image? Describe the main elements.
                        - type: image_url
                          image_url:
                            url: >-
                              https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg
                  max_tokens: 16384
                  temperature: 0.1
                  top_p: 1
                  stream: true
      responses:
        '200':
          description: Vision analysis completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisionResponse'
              example:
                id: chatcmpl-abc123
                object: chat.completion
                created: 1710000000
                model: Qwen/Qwen3-VL-Plus
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: >-
                        The image shows the Statue of Liberty standing on
                        Liberty Island in New York Harbor, with water and city
                        skyline elements visible in the background.
                    finish_reason: stop
                usage:
                  prompt_tokens: 120
                  completion_tokens: 48
                  total_tokens: 168
                x_metrics:
                  ttft_seconds: 0.41
                  tps: 38.4
                  total_time_seconds: 1.92
        '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 vision 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 vision provider is unavailable or returned an
            error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendUnavailableErrorResponse'
        '504':
          description: Gateway timeout - upstream vision provider took too long to respond
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    VisionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          example: Qwen/Qwen3-VL-Plus
          description: The multimodal vision-language model to use.
        messages:
          type: array
          description: Chat-style input containing text instructions and image content.
          items:
            type: object
            required:
              - role
              - content
            properties:
              role:
                type: string
                example: user
              content:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: text
                    text:
                      type: string
                      example: What is in this image? Describe the main elements.
                    image_url:
                      type: object
                      properties:
                        url:
                          type: string
                          example: https://example.com/sample-image.jpg
                          description: Publicly accessible image URL for visual analysis.
        max_tokens:
          type: integer
          default: 16384
          description: Maximum number of tokens to generate in the response.
        temperature:
          type: number
          default: 0.1
          description: Sampling temperature controlling response variability.
        top_p:
          type: number
          default: 1
          description: Nucleus sampling parameter.
        stream:
          type: boolean
          default: true
          description: Whether to stream output incrementally.
    VisionResponse:
      type: object
      description: Standard OpenAI-compatible chat completion response or streamed chunks.
      properties:
        id:
          type: string
          example: chatcmpl-abc123
        object:
          type: string
          example: chat.completion
        created:
          type: integer
          example: 1710000000
        model:
          type: string
          example: Qwen/Qwen3-VL-Plus
        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: >-
                      The image shows the Statue of Liberty standing on Liberty
                      Island in New York Harbor.
              finish_reason:
                type: string
                example: stop
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
              example: 120
            completion_tokens:
              type: integer
              example: 48
            total_tokens:
              type: integer
              example: 168
        x_metrics:
          type: object
          description: Performance metrics for the request.
          properties:
            ttft_seconds:
              type: number
              example: 0.41
            tps:
              type: number
              example: 38.4
            total_time_seconds:
              type: number
              example: 1.92
    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.
    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
    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
    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
    ModelNotFoundErrorResponse:
      type: object
      description: Returned when the specified 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 'vision-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
    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
    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 vision 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 vision 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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````