Image Description API for Captions & Scene Understanding

API Endpoint Access URL

https://api.pixlab.io/describe

Description

The DESCRIBE API endpoint generates natural-language descriptions of images and video frames from a single request. It is useful for accessibility features, alt text generation, catalog enrichment, moderation review, creative workflows, and any product surface that needs a readable summary of visual content.

Developers can use it to produce full captions or shorter summaries in multiple languages without building a custom captioning pipeline. The endpoint fits well in media platforms, ecommerce tools, internal review systems, and automation flows that need structured vision output expressed as text.

HTTP Methods

GET, POST

HTTP Parameters

Required

Fields	Type	Description
`img`	URL	URL to the input image to generate a description for in the event of a `GET` request. If you want to upload an image directly from your app, then submit a `multipart/form-data` POST request instead. Refer to the POST Request Data section below.
`key`	String	Your PixLab API Key ↗. You can also send the key in the `WWW-Authenticate` HTTP header and omit this parameter.

Optional

Fields	Type	Description
`lang`	String	Response language. Defaults to `english`.
`short`	Boolean	Set to `true` to return a shorter caption instead of a more detailed description. Defaults to `false`.

POST Request Body

This section explains when to use a POST request instead of a simple GET request.

Allowed Content-Types:

multipart/form-data
application/json

Use multipart/form-data to upload an image directly from your app. Refer to the PixLab GitHub Repository ↗ for a working example. If you're using application/json, pass a public image URL or a previously stored asset reference in img. The store endpoint can help when you want to upload media before invoking this endpoint.

HTTP Response

application/json

This endpoint returns a JSON object containing the generated image description. Response fields include:

Fields	Type	Description
`status`	Integer	HTTP 200 indicates success. Any other code indicates failure.
`description`	String	Generated caption or scene description for the submitted image, returned in the selected language.
`error`	String	Error details returned when `status` != 200.

Code Samples



import requests
import json

# Generate a natural-language description of image content.

# Target Image: Change to any link or switch to POST if you want to upload your image directly, refer to the REST API code samples for more info.
img = 'https://pixlab.io/assets/images/nature31.jpg' 

key = 'PIXLAB_API_KEY' # Get your API key from https://console.pixlab.io/

req = requests.get('https://api.pixlab.io/describe',params={
  'img':img,
  'key':key,
  'lang':'english',
  'short':False
})
reply = req.json()
if reply['status'] != 200:
	print (reply['error'])
else:
  description = reply['description']
  print(f"Natural language content description: {description}")


// Generate a natural-language description of image content.

// Target Image: Change to any link or switch to POST if you want to upload your image directly, refer to the REST API code samples for more info.
const img = 'https://pixlab.io/assets/images/nature31.jpg';

const key = 'PIXLAB_API_KEY'; // Get your API key from https://console.pixlab.io/

fetch('https://api.pixlab.io/describe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    img: img,
    key: key,
    lang: 'english',
    short: false
  })
})
  .then(response => response.json())
  .then(reply => {
    if (reply.status !== 200) {
      console.log(reply.error);
    } else {
      const description = reply.description;
      console.log(`Natural language content description: ${description}`);
    }
  })
  .catch(error => console.error('Error:', error));

<?php
# Generate a natural-language description of image content.

# Target Image: Change to any link or switch to POST if you want to upload your image directly, refer to the REST API code samples for more info.
$img = 'https://pixlab.io/assets/images/nature31.jpg';

$key = 'PIXLAB_API_KEY'; // Get your API key from https://console.pixlab.io/

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.pixlab.io/describe?img=' . urlencode($img) . '&key=' . $key . '&lang=english&short=false');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$reply = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($reply['status'] != 200) {
    echo $reply['error'];
} else {
    $description = $reply['description'];
    echo "Natural language content description: " . $description;
}


require 'net/http'
require 'json'

# Generate a natural-language description of image content.

# Target Image: Change to any link or switch to POST if you want to upload your image directly, refer to the REST API code samples for more info.
img = 'https://pixlab.io/assets/images/nature31.jpg'

key = 'PIXLAB_API_KEY' # Get your API key from https://console.pixlab.io/

uri = URI('https://api.pixlab.io/describe')
params = {
  'img' => img,
  'key' => key,
  'lang' => 'english',
  'short' => false
}

uri.query = URI.encode_www_form(params)
response = Net::HTTP.get_response(uri)
reply = JSON.parse(response.body)

if reply['status'] != 200
  puts reply['error']
else
  description = reply['description']
  puts "Natural language content description: #{description}"
end

Similar API Endpoints

tagimg, nsfw, img-embed, docscan, chat, text-embed, crop, mogrify, facelookup ↗, faceverify ↗, query