Image Description Generator REST API

The Image Description Generator REST API allows you to programmatically generate descriptions for images using our AI-powered service. The API supports multiple description modes and languages, making it perfect for accessibility, content management, and automation workflows.

API Documentation

URL: https://www.imagedescriptiongenerator.net/api/describe

Method: POST

Content-Type: application/json

Authorization: Bearer API_KEY

🤔

Authentication

Include your API key in the HTTP Authorization header using Bearer token format.

Authorization: Bearer API_KEY

🤔

Request Body Parameters

Parameter	Type	Required	Description
lang	string	Yes	Language code (e.g., "en-US", "es-ES", "fr-FR")
mode	string	Yes	Description mode (see modes below)
extra	string	No	Additional instructions for the description
allowAllImages	boolean	No	Allow processing of all image types (requires paid account)
image	string	No	Base64-encoded image data with data URI prefix. You must specify either this field, or imageUrl.
imageUrl	string	No	URL to an image. You must specify either this field, or image.
filename	string	No	Original filename for reference

🤔

Example Request Body

{
  "lang": "en-US",
  "mode": "detailed",
  "extra": "Focus on colors and composition",
  "allowAllImages": false,
  "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
  "filename": "example.jpg"
}

🤔

Description Modes

simple

A simple, brief, and accurate description

detailed

A detailed, meticulous description with all details

alt-text

Clear description under 125 characters for screen readers

Engaging tweet inspired by the image

instagram

Instagram post inspired by the image

extract-text

Extract only the text from the image

filename

Generate a descriptive filename for the image

character

Focus on the central person or character

narrative

Literary introduction for the central character

location

Identify the location shown in the image

image-gen

Description for text-to-image generation

🤔

Response

Success Response (200 OK)

{
  "description": "A beautiful sunset over a calm lake with mountains in the background. The sky is painted in vibrant shades of orange, pink, and purple, reflecting on the still water below."
}

🤔

Example Error Responses

401 Unauthorized

{
  "error": "Invalid API key"
}

400 Bad Request - Invalid Language

{
  "error": "Invalid language value",
  "field": "lang",
  "validValues": ["en-US", "en-GB", "es-ES", "fr-FR", ...]
}

400 Bad Request - Invalid Mode

{
  "error": "Invalid mode value",
  "field": "mode",
  "validValues": ["simple", "detailed", "alt-text", ...]
}

400 Bad Request - Out of Credits

{
  "error": "Account is out of credits"
}

🤔

Example Usage

cURL

curl -X POST https://www.imagedescriptiongenerator.net/api/describe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api key>" \
  -d '{
    "lang": "en-US",
    "mode": "detailed",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
  }'

JavaScript

const response = await fetch('https://www.imagedescriptiongenerator.net/api/describe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <api key>'
  },
  body: JSON.stringify({
    lang: 'en-US',
    mode: 'detailed',
    image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...'
  })
});

const result = await response.json();
console.log(result.description);