CaosLabs

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

bash

Authorization: Bearer YOUR_API_TOKEN

See API Tokens for how to generate your token.

API Endpoints

1. Generate Font Embedding

POST https://api.caoslabs.com/arcfont/embedding

Generate a numerical representation (embedding) of your font image that captures its visual characteristics.

Parameters:

file (required): Font image file (PNG, JPEG, JPG, or other image formats)
Maximum file size: 5MB

Request Examples:

cURL:

bash

curl -X POST "https://api.caoslabs.com/arcfont/embedding" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@your_font_image.png"

Python (requests):

python

  import requests
  url = "https://api.caoslabs.com/arcfont/embedding"
  token = "YOUR_API_TOKEN"

  headers = {
      "Authorization": f"Bearer {token}"
  }

  with open("your_font_image.png", "rb") as f:
      files = {"file": ("your_font_image.png", f, "image/png")}
      response = requests.post(url, files=files, headers=headers)
    
  embedding = response.json()
  print(embedding)

JavaScript (fetch):

javascript

const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('https://api.caoslabs.com/arcfont/embedding', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Response:

json

[0.1234, -0.5678, 0.9012, 0.3456, -0.7890, ...]

Returns an array of floating-point numbers representing your font's visual characteristics.

2. Compare Two Fonts

POST https://api.caoslabs.com/arcfont/font_comparison

Compare two font images and get similarity metrics between them.

NOTE: Generally a cosine similarity greater than 0.7 means the same or very similar font.

Parameters:

file1 (required): First font image file
file2 (required): Second font image file
Maximum file size per file: 5MB

Request Examples:

cURL:

bash

curl -X POST "https://api.caoslabs.com/arcfont/font_comparison" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file1=@font_a.png" \
  -F "file2=@font_b.png"

Python (requests):

python

import requests

url = "https://api.caoslabs.com/arcfont/font_comparison"
token = "YOUR_API_TOKEN"

headers = {
    "Authorization": f"Bearer {token}"
}

with open("font_a.png", "rb") as f1, open("font_b.png", "rb") as f2:
    files = {
        "file1": ("font_a.png", f1, "image/png"),
        "file2": ("font_b.png", f2, "image/png")
    }
    response = requests.post(url, files=files, headers=headers)
    
comparison = response.json()
print(comparison)

JavaScript (fetch):

javascript

const formData = new FormData();
formData.append('file1', file1Input.files[0]);
formData.append('file2', file2Input.files[0]);

fetch('https://api.caoslabs.com/arcfont/font_comparison', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Response:

json

{
  "cosine_distance": 0.234,
  "cosine_similarity": 0.766
}

Understanding the results:

cosine_similarity: Ranges from -1 to 1 (1 = identical, 0 = unrelated, -1 = opposite)
cosine_distance: Ranges from 0 to 2 (0 = identical, 2 = completely different)

3. Search for Similar Fonts

POST https://api.caoslabs.com/arcfont/font_search

Find fonts in our database that are visually similar to your input image.

Parameters:

file (required): Font image file to search for
k (optional): Number of similar fonts to return (default: 5, max: 10, min: 1)
Maximum file size: 5MB

Request Examples:

cURL:

bash

curl -X POST "https://api.caoslabs.com/arcfont/font_search" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@your_font.png" \
  -F "k=8"

Python (requests):

python

import requests

url = "https://api.caoslabs.com/arcfont/font_search"
token = "YOUR_API_TOKEN"

headers = {
    "Authorization": f"Bearer {token}"
}

with open("your_font.png", "rb") as f:
    files = {"file": ("your_font.png", f, "image/png")}
    data = {"k": 8}  # Get top 8 similar fonts
    response = requests.post(url, files=files, data=data, headers=headers)
    
results = response.json()
print(results)

JavaScript (fetch):

javascript

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('k', '8');

fetch('https://api.caoslabs.com/arcfont/font_search', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

Response:

json

[
  {
    "font_name": "Arial-Bold",
    "font_family": "Arial",
    "variant": "Bold",
    "version": "1.0",
    "category": "Sans-serif",
    "source_url": "https://example.com/arial-bold",
    "distance": 0.123
  },
  {
    "font_name": "Helvetica-Regular",
    "font_family": "Helvetica",
    "variant": "Regular",
    "version": "2.1",
    "category": "Sans-serif",
    "source_url": "https://example.com/helvetica",
    "distance": 0.156
  }
]

HTTP Status Codes

200 OK: Request successful
400 Bad Request: Invalid file format or corrupted file
401 Unauthorized: Invalid or missing API token
413 Payload Too Large: File exceeds 5MB limit
422 Unprocessable Entity: Invalid file format for font processing
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Service temporarily unavailable
502/503 Service Unavailable: Font processing service temporarily down
504 Gateway Timeout: Request timed out (try smaller files)

Next Steps

Check out Best Practices and Examples for optimal image preparation
Read about API Tokens for authentication setup

ArcFont API Reference

Authentication

API Endpoints

1. Generate Font Embedding

2. Compare Two Fonts

3. Search for Similar Fonts

HTTP Status Codes

Next Steps