API Documentation

Getting Started

To use the ImgTags API, you'll need an API key. Sign up for a free account to get started.

Step 2: Generate an API key from your dashboard

Step 3: Start making requests with your API key

Base URL

https://www.imgtags.com/api/v1

Authentication

All API requests require authentication using a Bearer token in the Authorization header. Include your API key in every request.

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key. You can create and manage API keys from your dashboard.

Endpoints

POST

/analyze

Analyze an image and get detailed tags, objects, colors, and metadata. You can provide the image either as a URL or by uploading a file.

Analyze Image from URL

Send a POST request with the image URL in the request body as JSON.

curl -X POST "https://www.imgtags.com/api/v1/analyze" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://example.com/image.jpg"
}'

Request Parameters (JSON)

url (required) - The URL of the image to analyze. Must be a valid URL and maximum 2048 characters.

Analyze Image from File Upload

Send a POST request with the image file as multipart/form-data.

curl -X POST "https://www.imgtags.com/api/v1/analyze" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -F "image=@/path/to/image.jpg"

Request Parameters (Multipart Form Data)

image (required) - The image file to analyze. Supported formats: JPEG, PNG, GIF, WebP. Maximum file size: 10MB.

Success Response

HTTP 200 OK

{
  "success": true,
  "data": {
    "tags": ["sunset", "beach", "ocean", "nature"],
    "description": "A vibrant sunset over a calm ocean beach",
    "objects": ["sun", "water", "sand", "clouds"],
    "colors": {
      "dominant": "#FF6B35",
      "palette": ["#FF6B35", "#004E89", "#1A1A2E"]
    },
    "scene": "outdoor",
    "mood": "peaceful",
    "safe_search": {
      "adult": "VERY_UNLIKELY",
      "violence": "VERY_UNLIKELY"
    },
    "dimensions": {
      "orientation": "landscape"
    }
  },
  "meta": {
    "tokens_used": 1250,
    "processing_time_ms": 1234
  }
}

Response Fields

success - Boolean indicating if the request was successful
data - The analysis results object containing:
- tags - Array of relevant tags describing the image
- description - A brief description of the image
- objects - Array of detected objects in the image
- colors - Object with dominant color and palette array (hex colors)
- scene - Type of scene (indoor/outdoor/abstract/etc)
- mood - Emotional tone of the image
- safe_search - Content safety detection with adult and violence likelihood (VERY_UNLIKELY, UNLIKELY, POSSIBLE, LIKELY, VERY_LIKELY)
- dimensions - Object with orientation (landscape/portrait/square)
meta - Metadata about the request:
- tokens_used - Number of tokens consumed by the AI model
- processing_time_ms - Processing time in milliseconds

Error Responses

HTTP 429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "type": "minute",
    "limit": 60,
    "reset": "2025-01-15T10:30:00Z"
  }
}

HTTP 422 Unprocessable Entity

{
  "message": "Either a URL or an image file is required.",
  "errors": {
    "url": ["The url field is required when image is not present."]
  }
}

HTTP 500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "ANALYSIS_FAILED",
    "message": "Failed to fetch image from URL"
  }
}

Code Examples

JavaScript (Fetch API)

// Analyze from URL
const response = await fetch('https://www.imgtags.com/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com/image.jpg'
  })
});

const data = await response.json();
console.log(data);

// Analyze from file upload
const formData = new FormData();
formData.append('image', fileInput.files[0]);

const uploadResponse = await fetch('https://www.imgtags.com/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  },
  body: formData
});

const uploadData = await uploadResponse.json();
console.log(uploadData);

Python (requests)

import requests

# Analyze from URL
url = 'https://www.imgtags.com/api/v1/analyze'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}
data = {
    'url': 'https://example.com/image.jpg'
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

# Analyze from file upload
with open('image.jpg', 'rb') as f:
    files = {'image': f}
    headers = {'Authorization': 'Bearer YOUR_API_KEY'}
    response = requests.post(url, headers=headers, files=files)
    result = response.json()
    print(result)

PHP (cURL)

// Analyze from URL
$ch = curl_init('https://www.imgtags.com/api/v1/analyze');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'url' => 'https://example.com/image.jpg'
]));

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

// Analyze from file upload
$ch = curl_init('https://www.imgtags.com/api/v1/analyze');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
]);
$file = new CURLFile('image.jpg', 'image/jpeg', 'image.jpg');
curl_setopt($ch, CURLOPT_POSTFIELDS, ['image' => $file]);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

Rate Limits

Free Tier

5 requests per day
1 request per minute
IP-based rate limiting (no API key required)

Pro Tier

10,000 requests per month
60 requests per minute
API key-based rate limiting
Multiple API keys supported

When rate limits are exceeded, you'll receive a 429 Too Many Requests response with details about when the limit resets.

Supported Image Formats

JPEG / JPG
PNG
GIF
WebP

Maximum file size: 10MB for file uploads. Image URLs must be publicly accessible.

Error Codes

Code	HTTP Status	Description
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded. Check the reset timestamp in the error response.
`ANALYSIS_FAILED`	500	Image analysis failed. Check the error message for details.
Validation Error	422	Request validation failed. Check that you've provided either a URL or image file.