Image Describer API Documentation (V2)
2025-08-18
Posted by
Image Describer API Documentation (V2)
Introduction & Use Cases
Image Describer API allows you to integrate AI-powered image description capabilities into your applications. Our API uses advanced AI models to analyze images and generate detailed descriptions.
Common Use Cases
- Generate detailed descriptions for images
- Extract text and information from images
- Analyze image content and context
- Create character descriptions for creative writing
- Generate image captions for content management
API Keys
To use our API, you'll need to obtain API credentials (API Key and Secret). You can manage your API keys in the dashboard.
API Endpoint
POST https://imagedescriber.online/api/openapi-v2/describe-image
Integration Guide
Request Headers
| Header Name | Required | Description |
|---|---|---|
| content-type | Yes | Must be multipart/form-data |
| authorization | Yes | Must be Bearer ${SECRET_KEY} ${SECRET_KEY} is your API key. |
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| image | string or file | Yes | Image to generate description. It accepts three input formats: 1. Image URL, starting with http:// or https://. 2. Base64 Encoded Image, following the format: data:image/jpeg;base64,/9j/4AAQSkZJR... (Note: other image types like PNG are also possible, adjust the mime-type accordingly) 3. File Object: A file object representing the model image. |
| prompt | string | Yes | Custom prompt for image analysis |
| lang | string | No | Response language (en/zh/de/es/fr/ja/ko/fi/nl/pt/tr/ru), default: en |
Response Format
| Field | Type | Description |
|---|---|---|
| code | number | Response status code. 200 for success |
| data | object | Response data object, present when code is 200 |
| data.content | string | The generated description for the image |
| msg | string | Response message, provides additional information |
| succeed | boolean | Indicates whether the request was successful |
Example Response
{
"code": 200,
"data": {
"content": "Detailed description of the image in markdown format..."
},
"succeed": true,
"msg": "Success"
}
Error Codes
| Code | Message | Description |
|---|---|---|
| 200 | OK | Request successful |
| 500 | SERVER_ERROR | Internal server error |
| 10003 | INSUFFICIENT_CREDITS | Insufficient credits |
| 10004 | INVALID_PARAM | Invalid parameters |
| 10005 | HARMFUL_CONTENT | Harmful content detected |
| 30001 | INVALID_API_KEY | Invalid API key |
| 30002 | INVALID_SIGNATURE | Invalid request signature |
Code Examples
Curl Example With Image Url
curl --location 'https://imagedescriber.online/api/openapi-v2/describe-image' \
--header 'Authorization: Bearer ${SECRET_KEY}' \
--form 'image="https://persistent.imagedescriber.online/image-describer-examples/000.jpg"' \
--form 'prompt="Briefly describe the content of the image"' \
--form 'lang="en"'
Curl Example With Local Image File
curl --location 'https://imagedescriber.online/api/openapi-v2/describe-image' \
--header 'Authorization: Bearer ${SECRET_KEY}' \
--form 'image=@"/PATH/TO/YOUR/IMAGE.jpg"' \
--form 'prompt="Briefly describe the content of the image"' \
--form 'lang="en"'
Curl Example With Image Base64
curl --location 'https://imagedescriber.online/api/openapi-v2/describe-image' \
--header 'Authorization: Bearer ${SECRET_KEY}' \
--form 'image="data:image/jpeg;base64,/9j……/9k="' \
--form 'prompt="Briefly describe the content of the image"' \
--form 'lang="en"'
Node.js Example
async function callDescribeImageApi() {
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
const formData = new FormData();
formData.append('image', ...); // Support url, image file, image base64 encode
formData.append('prompt', 'Briefly describe the content of the image');
formData.append('lang', 'en'); // Response language code
const apiEndpoint = 'https://imagedescriber.online/api/openapi-v2/describe-image';
try {
const response = await fetch(apiEndpoint, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
},
body: formData,
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(`HTTP error ${response.status}: ${errorData.msg || 'Unknown error'}`);
}
const data = await response.json();
return { content: data.data.content, error: null };
} catch (error) {
console.error('Error describing image:', error);
return { content: null, error: error.message };
}
}
Python Example
import requests
import base64
async def call_describe_image_api():
api_key = 'YOUR_API_KEY' # Replace with your actual API key
form_data = {
'image': 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...', # Example base64 image. Replace with your actual image data. Supports url, file, and base64.
'prompt': 'Briefly describe the content of the image',
'lang': 'en' # Example description. Remove this line if garmentDesc is empty
}
api_endpoint = 'https://imagedescriber.online/api/openapi-v2/describe-image'
try:
headers = {
'Authorization': f'Bearer {api_key}',
}
response = requests.post(api_endpoint, files=form_data, headers=headers) # Use files= for multipart/form-data
response.raise_for_status() # Raise an exception for bad status codes (4xx or 5xx)
data = response.json()
return {'content': data.get('data', {}).get('content'), 'error': None}
except requests.exceptions.RequestException as e:
print(f'Error describing image: {e}')
return {'content': None, 'error': str(e)}
Pricing
API calls consume credits from your account. You can purchase credits on our pricing page.
Help & Support
If you have any questions or need assistance, please don't hesitate to contact our support team.
Email: [email protected]