Image Tagging

Automatically generate tags, classify images, and detect objects using CoreViz's advanced vision models. Perfect for content organization, moderation, and automated categorization.

Interactive Demo

Try it out ↓

Endpoint

POST /api/ai/tag

Headers

Header	Value	Required
`Content-Type`	`application/json`	Yes
`x-api-key`	Your API key	Yes

Request Body

Field	Type	Required	Description
`image`	string	Yes	URL of the image to tag
`prompt`	string	No	Custom prompt for tagging (e.g., "objects in the image", "identify all animals")
`choices`	string[]	No	List of classification choices (e.g., ["receipt", "invoice", "document"])
`single`	boolean	No	Return only the best match when using choices (default: false)

Example Request

Basic Tagging

curl -X POST https://lab.coreviz.io/api/ai/tag \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image": "https://example.com/input.jpg"
  }'

Tagging with Custom Prompt

curl -X POST https://lab.coreviz.io/api/ai/tag \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image": "https://example.com/input.jpg",
    "prompt": "identify all animals in the image"
  }'

Classification with Choices

curl -X POST https://lab.coreviz.io/api/ai/tag \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image": "https://example.com/document.jpg",
    "choices": ["receipt", "invoice", "contract", "other"],
    "single": true
  }'

Response

Status Code: 200 OK

Response Body (Basic Tagging):

{
  "tags": [
    {
      "tag": "person",
      "confidence": 0.95
    },
    {
      "tag": "outdoor",
      "confidence": 0.87
    },
    {
      "tag": "nature",
      "confidence": 0.82
    }
  ]
}

Response Body (Classification with Choices):

{
  "classification": "invoice",
  "confidence": 0.92,
  "all_scores": [
    {
      "choice": "receipt",
      "score": 0.15
    },
    {
      "choice": "invoice",
      "score": 0.92
    },
    {
      "choice": "contract",
      "score": 0.08
    },
    {
      "choice": "other",
      "score": 0.05
    }
  ]
}

Response Fields

Basic Tagging Response

Field	Type	Description
`tags`	array	List of detected tags
`tags[].tag`	string	The tag name
`tags[].confidence`	number	Confidence score (0-1)

Classification Response

Field	Type	Description
`classification`	string	The best matching classification (when `single: true`)
`confidence`	number	Confidence score for the classification (0-1)
`all_scores`	array	Scores for all choices (when `single: false`)
`all_scores[].choice`	string	The classification choice
`all_scores[].score`	number	Score for this choice (0-1)

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

400 Bad Request

Invalid request parameters:

{
  "error": "Bad Request",
  "message": "Invalid image URL or missing required fields"
}

422 Unprocessable Entity

Image could not be processed:

{
  "error": "Unprocessable Entity",
  "message": "Unable to process the provided image"
}

Example Usage

JavaScript/TypeScript

const apiKey = 'YOUR_API_KEY';
const imageUrl = 'https://example.com/input.jpg';

// Basic tagging
const response = await fetch('https://lab.coreviz.io/api/ai/tag', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify({
    image: imageUrl,
  }),
});

const data = await response.json();
console.log('Tags:', data.tags);

// Classification
const classificationResponse = await fetch('https://lab.coreviz.io/api/ai/tag', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify({
    image: imageUrl,
    choices: ['receipt', 'invoice', 'contract', 'other'],
    single: true,
  }),
});

const classificationData = await classificationResponse.json();
console.log('Classification:', classificationData.classification);

Python

import requests

api_key = 'YOUR_API_KEY'
image_url = 'https://example.com/input.jpg'

# Basic tagging
response = requests.post(
    'https://lab.coreviz.io/api/ai/tag',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key,
    },
    json={
        'image': image_url,
    }
)

data = response.json()
print('Tags:', data['tags'])

# Classification
classification_response = requests.post(
    'https://lab.coreviz.io/api/ai/tag',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key,
    },
    json={
        'image': image_url,
        'choices': ['receipt', 'invoice', 'contract', 'other'],
        'single': True,
    }
)

classification_data = classification_response.json()
print('Classification:', classification_data['classification'])

Node.js

const fetch = require('node-fetch');

const apiKey = 'YOUR_API_KEY';
const imageUrl = 'https://example.com/input.jpg';

fetch('https://lab.coreviz.io/api/ai/tag', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify({
    image: imageUrl,
    prompt: 'identify all objects',
  }),
})
  .then((res) => res.json())
  .then((data) => {
    console.log('Tags:', data.tags);
  });

Use Cases

Content Organization

Automatically tag uploaded images for better organization:

async function organizeImage(imageUrl) {
  const response = await fetch('https://lab.coreviz.io/api/ai/tag', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({ image: imageUrl }),
  });
  
  const { tags } = await response.json();
  // Save tags to your database
  await saveImageTags(imageUrl, tags);
}

Document Classification

Classify documents automatically:

async function classifyDocument(imageUrl) {
  const response = await fetch('https://lab.coreviz.io/api/ai/tag', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      image: imageUrl,
      choices: ['receipt', 'invoice', 'contract', 'other'],
      single: true,
    }),
  });
  
  const { classification, confidence } = await response.json();
  return { type: classification, confidence };
}

Content Moderation

Detect inappropriate content:

async function moderateImage(imageUrl) {
  const response = await fetch('https://lab.coreviz.io/api/ai/tag', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      image: imageUrl,
      prompt: 'identify if this image contains inappropriate content',
    }),
  });
  
  const { tags } = await response.json();
  return tags.some(tag => tag.tag === 'inappropriate' && tag.confidence > 0.8);
}

E-commerce Product Tagging

Automatically tag product images:

async function tagProduct(imageUrl) {
  const response = await fetch('https://lab.coreviz.io/api/ai/tag', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      image: imageUrl,
      prompt: 'identify product category, color, style, and features',
    }),
  });
  
  const { tags } = await response.json();
  return tags;
}

Supported Image Formats

The API supports common image formats:

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
GIF (.gif)

Image URL Requirements

The image URL must be publicly accessible
HTTPS URLs are recommended
The image must be a valid image file
Maximum file size limits may apply (check your plan)

Notes

Tags are generated using advanced vision models
Confidence scores indicate the model's certainty
Custom prompts allow you to focus on specific aspects
Classification with choices is useful for structured categorization
Processing time varies based on image complexity
Results may vary slightly on subsequent requests due to AI model variations

Learn More

Try the Image Tagging Tool to test the API interactively
Explore Image Description for generating descriptions
Check out Image Embeddings for search capabilities
Visit CoreViz Studio for bulk processing

Image Tagging

On this page