Image Analysis API

The Image Analysis API allows you to analyze images using InsightEmbed's AI capabilities. This API enables visual content understanding for images uploaded directly or referenced by URL.

Analyzing Images

Analyze Uploaded Image

POST /analyze/image

Analyze an image uploaded directly to the API.

Request Parameters

This endpoint accepts multipart/form-data with the following fields:

Parameter	Type	Required	Description
image	file	Yes	The image file to analyze
prompt_template	string	No	Custom prompt template to guide the analysis
max_tokens	integer	No	Maximum number of tokens in the response (default: 256)
context	string	No	Additional context about the image to improve analysis

Example Request

curl -X POST https://api.insightembed.com/v1/analyze/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  -F "prompt_template=Describe what's in this image in detail" \
  -F "max_tokens=200" \
  -F "context=Product photography"

Example Response

{
  "success": true,
  "data": {
    "analysis": "The image shows a sleek modern smartphone with a black bezel-less design displayed at an angle. The phone has a large touchscreen displaying a colorful home screen with app icons. The device appears to be a premium model with a thin profile and metallic edges. The background is a gradient of soft blue, giving the product a professional, high-tech appearance typical of product photography.",
    "tokens_used": 68,
    "analysis_id": "ana_5e6f7g8h9i0j",
    "image_id": "img_1a2b3c4d5e6f"
  },
  "meta": {
    "processing_time": 1.23
  }
}

Analyze Image from URL

POST /analyze/image/url

Analyze an image referenced by a URL.

Request Parameters

Parameter	Type	Required	Description
image_url	string	Yes	URL of the image to analyze
prompt_template	string	No	Custom prompt template to guide the analysis
max_tokens	integer	No	Maximum number of tokens in the response (default: 256)
context	string	No	Additional context about the image to improve analysis

Example Request

{
  "image_url": "https://example.com/images/product.jpg",
  "prompt_template": "What are the main visual elements in this image?",
  "max_tokens": 150,
  "context": "E-commerce product listing"
}

Example Response

{
  "success": true,
  "data": {
    "analysis": "The main visual elements in this image include: 1) A white wireless headphone set positioned centrally, 2) A minimalist light gray background that creates contrast with the product, 3) Soft shadows beneath the headphones giving depth, 4) The brand logo visible on the ear cups, 5) A subtle reflection on the surface below the product enhancing the premium feel.",
    "tokens_used": 62,
    "analysis_id": "ana_6f7g8h9i0j1k",
    "image_id": "img_2b3c4d5e6f7g"
  },
  "meta": {
    "processing_time": 0.98
  }
}

Batch Image Analysis

Analyze Multiple Images

POST /analyze/image/batch

Analyze multiple images in a single request to reduce API calls.

Request Parameters

Parameter	Type	Required	Description
images	array	Yes	Array of image URLs to analyze
prompt_template	string	No	Custom prompt template for all images
max_tokens_per_image	integer	No	Maximum tokens per response (default: 128)
context	string	No	Shared context for all images

Example Request

{
  "images": [
    {
      "id": "img1",
      "url": "https://example.com/images/product1.jpg"
    },
    {
      "id": "img2",
      "url": "https://example.com/images/product2.jpg"
    }
  ],
  "prompt_template": "Describe this product briefly",
  "max_tokens_per_image": 75,
  "context": "Product catalog"
}

Example Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "img1",
        "analysis": "A pair of red running shoes with mesh upper, white midsole, and black rubber outsole. Features visible cushioning technology and reflective details.",
        "tokens_used": 25,
        "image_id": "img_3c4d5e6f7g8h"
      },
      {
        "id": "img2",
        "analysis": "A black fitness tracker wristband with a rectangular OLED display. The slim design features a textured band and visible heart rate sensor on the underside.",
        "tokens_used": 28,
        "image_id": "img_4d5e6f7g8h9i"
      }
    ],
    "batch_id": "bat_8h9i0j1k2l3m"
  },
  "meta": {
    "processing_time": 2.45,
    "total_tokens_used": 53
  }
}

Image OCR (Text Extraction)

Extract Text from Image

POST /analyze/image/ocr

Extract and analyze text content from images.

Request Parameters

Parameter	Type	Required	Description
image_url	string	No*	URL of the image to analyze
image	file	No*	Image file to analyze (for multipart/form-data)
language	string	No	Primary language in the image (ISO code, e.g., 'en')
analyze_text	boolean	No	Whether to analyze the extracted text (default: false)
prompt_template	string	No	Custom prompt template if analyzing text

*Either image_url or image must be provided.

Example Request

{
  "image_url": "https://example.com/images/document.jpg",
  "language": "en",
  "analyze_text": true,
  "prompt_template": "Summarize the key points in this text"
}

Example Response

{
  "success": true,
  "data": {
    "extracted_text": "InsightEmbed Terms of Service\n\nEffective Date: January 1, 2023\n\n1. Introduction\nWelcome to InsightEmbed, a service that provides AI-powered content analysis through an embeddable widget. By using our service, you agree to these Terms of Service.\n\n2. Subscription Plans\nInsightEmbed offers three subscription tiers: Free, Starter, and Pro. Each plan includes different features and usage limits as described on our pricing page.",
    "text_analysis": "Key points: 1) Document is InsightEmbed's Terms of Service effective January 1, 2023, 2) Service provides AI-powered content analysis via embeddable widget, 3) Usage requires agreement to terms, 4) Three subscription tiers are available (Free, Starter, Pro) with different features and limits.",
    "tokens_used": 52,
    "analysis_id": "ana_7g8h9i0j1k2l",
    "image_id": "img_5e6f7g8h9i0j"
  },
  "meta": {
    "processing_time": 1.76
  }
}

Error Handling

The Image Analysis API uses standard HTTP status codes and returns detailed error information in the response body.

Common Errors

Status Code	Error Code	Description
400	invalid_request	Missing required parameters or invalid format
401	authentication_error	Invalid or missing API key
403	forbidden	The API key doesn't have permission for this operation
413	image_too_large	The submitted image exceeds size limits
415	unsupported_media_type	The image format is not supported
422	processing_failed	Failed to process the image
429	rate_limit_exceeded	You've exceeded your rate limit
500	service_error	Internal service error

Error Response Example

{
  "success": false,
  "error": {
    "code": "image_too_large",
    "message": "The submitted image exceeds the maximum size of 5MB",
    "param": "image"
  }
}

Best Practices

1. Optimize Image Size: Resize images to appropriate dimensions before uploading to reduce processing time and bandwidth.

2. Provide Context: Include relevant context about the image to improve analysis quality.

3. Use Custom Prompts: Tailor the analysis by providing custom prompt templates for your specific use case.

4. Batch Processing: Use the batch API for analyzing multiple related images to reduce API calls.

5. Choose Appropriate Formats: Use JPEG for photographs and PNG for graphics with text or transparent elements.

6. OCR Optimization: For text extraction, ensure images have good contrast and resolution for optimal results.

Supported Image Formats

• JPEG/JPG
• PNG
• GIF (first frame only)
• BMP
• WEBP
• HEIC/HEIF

Quotas and Limits

Plan	Daily Image Analysis Limit	Max Image Size	Max Batch Size
Free	50 images	5 MB	5 images
Starter	200 images	10 MB	10 images
Pro	1,000 images	20 MB	20 images

For more information about quotas and rate limits, see the API Reference Overview.