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

# Font recognition

> Identify the closest matching open-source font from an image

Analyze a public image URL and return ranked open-source font matches for the largest readable word in the image.

<Card title="Font recognition guide" icon="scan-search" href="/guides/font-recognition" horizontal>
  Learn when to use font recognition and see a complete example response.
</Card>


## OpenAPI

````yaml api-reference/font-recognition-openapi.json POST /v1/api/lens
openapi: 3.1.0
info:
  title: Mixfont Font Recognition API
  description: Identify the closest matching open source font from an image URL.
  version: 1.0.0
servers:
  - url: https://api.mixfont.com
security: []
paths:
  /v1/api/lens:
    post:
      summary: Font recognition
      description: >-
        Analyze an image URL and return ranked open source font matches for the
        largest readable word.
      operationId: postFontRecognition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FontRecognitionRequest'
            example:
              image_url: https://images.example.com/wordmark.png
              top_k: 3
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FontRecognitionResponse'
              example:
                word: Mixfont
                word_box:
                  left: 140
                  top: 96
                  width: 412
                  height: 104
                input_image:
                  width: 1600
                  height: 900
                  image_url: https://images.example.com/wordmark.png
                font_matches:
                  - name: Inter
                    score: 0.83
                    fonts:
                      - full_name: Inter Regular
                        style: normal
                        weight: 400
                        url: >-
                          https://static.mixfont.com/fonts/inter/Inter-Regular.ttf
                      - full_name: Inter Italic
                        style: italic
                        weight: 400
                        url: >-
                          https://static.mixfont.com/fonts/inter/Inter-Italic.ttf
                  - name: Public Sans
                    score: 0.11
                    fonts:
                      - full_name: Public Sans Regular
                        style: normal
                        weight: 400
                        url: >-
                          https://static.mixfont.com/fonts/public-sans/PublicSans-Regular.ttf
                requestId: 7d58a66d-f129-4f9a-bf9a-4f2c6d0c3e4d
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  image_url must be a string and top_k must be an integer
                  between 1 and 10.
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized.
        '402':
          description: Not enough credits remaining
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Current team does not have enough API credits remaining.
        '403':
          description: The API key cannot resolve a valid team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Team associated with this API key could not be resolved.
        '502':
          description: Upstream font recognition service failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: The font recognition service failed to process the request.
        '504':
          description: Request timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Inference request timed out after 90 seconds.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    FontRecognitionRequest:
      type: object
      required:
        - image_url
      properties:
        image_url:
          type: string
          format: uri
          description: >-
            Public `http://` or `https://` image URL to analyze. The image
            response must be no larger than 10 MB.
        top_k:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
          description: Number of font matches to return.
    FontRecognitionResponse:
      type: object
      required:
        - word
        - word_box
        - input_image
        - font_matches
      properties:
        word:
          type:
            - string
            - 'null'
          description: >-
            Largest detected word in the image. This can be `null` if no
            confident word is found.
        word_box:
          anyOf:
            - $ref: '#/components/schemas/WordBox'
            - type: 'null'
          description: >-
            Location of the detected word in the original image. This can be
            `null` if detection falls back to the full image.
        input_image:
          $ref: '#/components/schemas/InputImage'
        font_matches:
          type: array
          description: Ranked font matches, sorted best first.
          items:
            $ref: '#/components/schemas/FontMatch'
        requestId:
          type: string
          description: Request identifier to share with support.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong.
        requestId:
          type: string
          description: Request identifier to share with support when available.
    WordBox:
      type: object
      required:
        - left
        - top
        - width
        - height
      properties:
        left:
          type: integer
          description: Left offset of the detected word in pixels.
        top:
          type: integer
          description: Top offset of the detected word in pixels.
        width:
          type: integer
          description: Width of the detected word box in pixels.
        height:
          type: integer
          description: Height of the detected word box in pixels.
    InputImage:
      type: object
      required:
        - width
        - height
        - image_url
      properties:
        width:
          type: integer
          description: Original image width in pixels.
        height:
          type: integer
          description: Original image height in pixels.
        image_url:
          type: string
          format: uri
          description: Image URL sent to the API.
    FontMatch:
      type: object
      required:
        - name
        - score
        - fonts
      properties:
        name:
          type: string
          description: Name of the matched font family.
        score:
          type: number
          description: Similarity score for the match.
        fonts:
          type: array
          description: Downloadable font files for that family when available.
          items:
            $ref: '#/components/schemas/FontFile'
    FontFile:
      type: object
      required:
        - full_name
        - style
        - weight
        - url
      properties:
        full_name:
          type: string
          description: Full font file name.
        style:
          type: string
          description: Font style such as `normal` or `italic`.
        weight:
          type: integer
          description: Numeric font weight.
        url:
          type: string
          description: >-
            Download URL for the font file, or an empty string when metadata is
            unavailable.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````