Skip to main content
Use the Alt Magic REST API to programmatically generate descriptive, SEO-optimized alt text for images using advanced AI models with automatic fallback capabilities.

​
Introduction

The Alt Magic API allows you to make a POST request to generate alt text for any image. You can configure parameters in the API request body or provide additional context for better results. The API automatically falls back from Gemini to OpenAI if needed, ensuring maximum reliability.

​
How It Works

  1. Create an API key in your Alt Magic dashboard
  2. Share your image either by:
    • Providing a publicly accessible URL (image_url), or
    • Uploading the image file directly as base64 data URI (image_file)
  3. Make a POST request to your personal Alt Magic endpoint
  4. Track the response and get your generated alt text

​
Setting Up Parameters

​
Required Parameters

  • user_id - Your unique identifier (email address)
  • Either image_url OR image_file - You must provide one of these:
    • image_url - Publicly accessible URL of the image
    • image_file - Image file in data URI format with base64 encoded image data (format: data:image/[type];base64,[base64-data])

​
Optional Parameters

  • blog_title - Context for better alt text generation
  • seo_keywords - Keywords for SEO optimization
  • language_code - Language for the generated text (All supported languages →).

​
Language Support

The Alt Magic API supports 200+ languages for generating alt text. You can specify the desired language using the language_code parameter in your requests. Popular Languages:
  • English (en) - Default language (fallback)
  • Spanish (es) - Español
  • French (fr) - Français
  • German (de) - Deutsch
  • Chinese (zh-CN, zh-TW) - 中文
  • Japanese (ja) - 日本語
  • Korean (ko) - 한국어
  • Arabic (ar) - العربية
  • Hindi (hi) - हिन्दी
  • Portuguese (pt, pt-BR) - Português
View complete language list →

​
Getting Your API Endpoint

Your API endpoint is automatically assigned when you create your account: Base URL: https://api.altmagic.pro Alt Text Generation: POST /v1/generate-alt-text-api - Generate AI-powered alt text for images with automatic fallback from Gemini to OpenAI. User Details: POST /v1/get-user-details-api - Retrieve user account information including subscription plan and available credits.

​
Authentication

The Alt Magic API uses API key authentication to ensure secure access. When making requests, you must include your unique API key in the x-api-key header. This key can be generated and managed from your Alt Magic dashboard. Keep your API key confidential and never expose it in client-side code or public repositories. API Key: Include the x-api-key header in your request for authentication (recommended for server-to-server integrations). 
x-api-key: YOUR_API_KEY_HERE

​
Rate Limits

Rate limits are applied per user to ensure fair usage:
  • Standard Rate Limit: 100 requests per minute

​
Error Handling

The API returns standard HTTP status codes with detailed error messages:
Status CodeMeaningDescription
200SuccessRequest was successful
400Bad RequestValidation errors in the request
401UnauthorizedAuthentication required
403ForbiddenInsufficient credits
429Too Many RequestsRate limit exceeded
500Internal Server ErrorAn error occurred on the server

​
Example Response

Each API request returns immediate results with your generated alt text. 
{
  "altText": "A close-up photo of a red apple on a wooden table with natural lighting",
  "CreditsAvailable": 49,
  "plan_type": "pro"
}

​
Complete API Examples

​
Option 1 (using image URL)

curl -X POST "https://api.altmagic.pro/v1/generate-alt-text-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "blog_title": "Healthy Eating Guide",
    "seo_keywords": "healthy, food, nutrition, apples",
    "language_code": "en",
    "user_id": "[email protected]"
  }'

​
Option 2 (using image file)

curl -X POST "https://api.altmagic.pro/v1/generate-alt-text-api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "image_file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k=",
    "user_id": "user123",
    "blog_title": "Beautiful Sunset Over Mountains",
    "seo_keywords": "sunset, mountains, nature, landscape, photography",
    "language_code": "en"
  }'
When using image_file, ensure your base64 data URI follows the format: data:image/[type];base64,[base64-data]. Supported image types include JPEG, PNG, GIF, and WebP.

​
Next Steps

  1. Generate your API key - Step-by-step guide
  2. Read the endpoint documentation for detailed parameters
Ready to get started? Generate your first API key →