Imagga Getting Started: API Key & First Image Tagging in 2026

Getting started overview

This guide outlines the process for new users to get started with Imagga's image recognition and tagging APIs. It covers account creation, API key retrieval, and making a foundational request to the Imagga Tagging API. Imagga provides several core products, including auto-tagging, categorization, color extraction, and cropping APIs, alongside custom training options for specialized use cases Imagga homepage. Integration is supported through official SDKs for Python, Java, Node.js, PHP, and Ruby, or direct HTTP requests.

The primary goal of this guide is to enable a user to successfully send an image to Imagga and receive a structured JSON response containing tags. This serves as a working foundation for integrating more complex features or specific API modules.

Here’s a quick reference for the steps involved:

Create an account and get keys

To begin using Imagga, you must first create an account. Imagga offers a free tier that includes up to 1,000 requests per month, which is sufficient for initial testing and development Imagga pricing plans. Paid plans start at $49 per month for 5,000 requests.

1. Navigate to the Imagga Pricing Page: Go to Imagga's official pricing page.
2. Select a Plan: Choose the 'Free' plan to start. This typically requires an email address and password for registration.
3. Complete Registration: Follow the on-screen prompts to set up your account. This may involve email verification.
4. Access Developer Dashboard: Once registered and logged in, you will be directed to your Imagga Developer Dashboard.
5. Locate API Keys: Within the dashboard, find the section labeled 'API Keys' or similar. Here, you will find your unique API Key and API Secret. These credentials are used for authenticating your requests to the Imagga API. Imagga uses HTTP Basic Authentication, where the API Key serves as the username and the API Secret as the password Imagga developer documentation.

It is crucial to keep your API Key and API Secret confidential. They should not be exposed in client-side code or public repositories. Store them securely, for example, using environment variables in server-side applications.

Your first request

With your API Key and Secret, you can now make your first call to the Imagga API. This example will use the Auto-tagging API, one of Imagga's core products Imagga homepage, to tag an image from a publicly accessible URL. We will demonstrate using curl for a direct HTTP request and provide examples for Node.js and Python using their respective SDKs.

Using cURL (HTTP Request)

The /v2/tags endpoint is used for image tagging. You'll need to replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials.

curl -u "YOUR_API_KEY:YOUR_API_SECRET" \
     "https://api.imagga.com/v2/tags?image_url=https://docs.imagga.com/static/img/example_photos/imagga_example_photo_1.jpg"

Expected JSON Response Structure:

{
  "result": {
    "tags": [
      {
        "confidence": 99.99,
        "tag": {
          "en": "sky"
        }
      },
      {
        "confidence": 99.98,
        "tag": {
          "en": "outdoor"
        }
      }
      // ... more tags
    ]
  },
  "status": {
    "text": "success",
    "type": "success"
  }
}

This response indicates that the image was successfully processed and provides a list of tags with associated confidence scores. The en field within the tag object represents the tag in English.

Using Node.js SDK

First, install the Imagga Node.js SDK:

npm install imagga-nodejs

Then, use the following code:

const Imagga = require('imagga-nodejs');

const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';

const imagga = new Imagga({ apiKey, apiSecret });

async function tagImage() {
  try {
    const response = await imagga.tagging.byUrl(
      'https://docs.imagga.com/static/img/example_photos/imagga_example_photo_1.jpg'
    );
    console.log('Node.js Tagging Response:', JSON.stringify(response.data, null, 2));
  } catch (error) {
    console.error('Error tagging image:', error.response ? error.response.data : error.message);
  }
}

tagImage();

Using Python SDK

First, install the Imagga Python SDK:

pip install imagga

Then, use the following code:

import os
from imagga import ImaggaClient

api_key = os.environ.get('IMAGGA_API_KEY', 'YOUR_API_KEY')
api_secret = os.environ.get('IMAGGA_API_SECRET', 'YOUR_API_SECRET')

client = ImaggaClient(api_key=api_key, api_secret=api_secret)

def tag_image():
    try:
        response = client.tagging.by_url(
            'https://docs.imagga.com/static/img/example_photos/imagga_example_photo_1.jpg'
        )
        print("Python Tagging Response:", response.json())
    except Exception as e:
        print(f"Error tagging image: {e}")

tag_image()

In the Python example, it is recommended to retrieve API keys from environment variables for security, as shown with os.environ.get. For local testing, directly assigning the keys is acceptable.

Common next steps

After successfully making your first request, consider these common next steps to further integrate Imagga into your application:

• Explore Other Endpoints: Imagga offers various APIs beyond basic tagging, such as Categorization, Color Extraction, and Cropping APIs. Review the Imagga developer documentation to understand their capabilities and how they can be applied to different use cases.
• Upload Local Files: Instead of image URLs, you might need to upload local image files directly. The Imagga API supports multipart/form-data uploads. Refer to the Imagga Tagging API reference for details on how to send image files.
• Implement Custom Training: For highly specialized tagging needs, Imagga provides a Custom Training API. This allows you to train the system with your own datasets to recognize specific objects, brands, or concepts relevant to your business Imagga homepage. This is particularly useful for e-commerce product categorization or niche content moderation.
• Handle Rate Limits and Error Codes: Understand Imagga's rate limits to prevent your application from being throttled. Implement proper error handling based on the API's response codes, which are detailed in the Imagga documentation. A common HTTP status code to anticipate is 429 Too Many Requests if rate limits are exceeded IETF RFC 6585 for 429 status code.
• Secure API Keys: Ensure your API keys are stored and transmitted securely. For server-side applications, use environment variables. For client-side applications, consider proxying requests through your own backend to prevent direct exposure of keys.
• Monitor Usage: Utilize the Imagga Developer Dashboard to monitor your API usage, track request counts, and manage your billing to stay within your plan limits.

Troubleshooting the first call

Encountering issues during the initial API call is common. Here are some troubleshooting tips:

• Check API Key and Secret: Double-check that your API Key and API Secret are correct and have no leading/trailing spaces. Ensure they are correctly passed in the Basic Authentication header.
• Verify URL: Confirm that the API endpoint URL is accurate (e.g., https://api.imagga.com/v2/tags).
• Image URL Accessibility: If using image_url, ensure the URL points to a publicly accessible image. Imagga's servers must be able to reach and download the image. Test the URL in a browser or with curl to confirm it's live and directly accessible.
• Network Issues: Check your local network connection and any firewalls that might be blocking outbound requests to Imagga's API.
• Rate Limit Exceeded (429 Error): If you receive a 429 Too Many Requests status code, you have exceeded your plan's request limit. Wait for the reset period or upgrade your plan. The free tier is limited to 1,000 requests per month Imagga pricing information.
• Invalid Parameters (400 Error): A 400 Bad Request usually indicates an issue with the parameters you sent. Review the Imagga Tagging API documentation to ensure all required parameters are present and correctly formatted. For example, ensure image_url is a valid URL string.
• Authentication Failure (401 Error): A 401 Unauthorized error means your credentials are incorrect or missing. Re-verify your API Key and Secret in your Imagga dashboard.
• Server Error (5xx Error): If you receive a 5xx server error, it indicates an issue on Imagga's side. These are typically temporary. You can check Imagga's status page (if available) or retry the request after a short delay.
• Consult Documentation: The Imagga developer documentation is the primary resource for detailed error codes and API usage.