Simple, powerful REST API

Generate SEO-optimized metadata for your images programmatically. Integrate AltText.io into any application with just a few lines of code.

Get API key View examples

Quick start

Get up and running in minutes with our simple REST API.

1. Get your API key

Generate your API key from your Settings page. All requests include your key in the request body — keep it secure and never expose it in client-side code.

2. Make your first request

Send a POST request with your image URL and target keyword, and get back an SEO-optimized title, description, and alt text in seconds.

3. Scale across languages and modes

Generate metadata in any supported language, switch to stock mode for ~35 buyer-focused keywords, or use the page metadata endpoint for posts and pages.

bash 
curl -X POST https://api.alttext.io/getmetadata \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your_api_key_here",
    "fileurl": "https://example.com/image.jpg",
    "keyword": "office productivity",
    "language": "english",
    "mode": "seo"
  }'

API endpoints

Authenticate by including your apikey in the JSON request body. Content-Type: application/json is required.

POST https://api.alttext.io/getmetadata

Generate a title, description, and alt text for an image. Supports SEO mode (keyword-optimized, 1 credit) and stock mode (buyer-focused metadata with ~35 keywords, 2 credits).

Parameters

apikey Required. Your AltText.io API key.
fileurl Required. URL of the image to process. Must be publicly accessible.
keyword Required for SEO mode only. The target SEO keyword for optimizing the metadata.
language Optional. Defaults to "english". See the supported languages below.
mode Optional. Defaults to "seo". Use "stock" for stock photography metadata.

Response

[
  {
    "title": "Woman using smartphone in modern office space",
    "description": "Professional woman in business attire checking smartphone while sitting at desk in bright modern office.",
    "alttext": "Woman checking smartphone at office desk"
  }
]
title SEO-optimized title for the image (typically 50–60 characters).
description Detailed description optimized for your keyword (max 200 characters).
alttext Concise alt text for accessibility (max 8 words).
keywords Stock mode only: approximately 35 comma-separated keywords focused on buyer search intent.
POST https://api.alttext.io/getpagemetadata

Generate SEO titles and meta descriptions for pages, posts, and custom post types. Text-only — no image URL required.

Parameters

apikey Required. Your API key (or send as an Authorization: Bearer <key> header).
title Required. The page/post title as authored. Used as the primary signal for the rewrite.
content Optional. Full page body (HTML, WordPress shortcodes, and Gutenberg block markers stripped server-side, capped at 20,000 characters). Strongly recommended — improves output quality significantly.
keyword Optional. Target SEO keyword. If omitted, the AI infers a primary keyword from the title and content.
language Optional. Defaults to "english". Same set as /getmetadata.

Response

[
  {
    "title": "Artisan Bakery in Seattle | Sourdough & Pastry",
    "meta_description": "Family-run artisan bakery in Seattle baking fresh sourdough, croissants, and seasonal pastries daily."
  }
]
title SEO-optimized title tag, constrained to 70 characters maximum (target: 50–60). Not server-truncated.
meta_description SEO meta description. Target: 150–160 characters. Not server-truncated.

Code examples

Get started quickly with examples in popular programming languages.

JavaScript (Node.js) 

const response = await fetch('https://api.alttext.io/getmetadata', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apikey: 'your_api_key_here',
    fileurl: 'https://example.com/image.jpg',
    keyword: 'office productivity',
    language: 'english',
    mode: 'seo'
  })
});

if (response.ok) {
  const metadata = await response.json();
  const { title, description, alttext } = metadata[0];
  console.log(title, description, alttext);
} else {
  const error = await response.json();
  console.error('Error:', error.error);
}

Python 

import requests

response = requests.post(
    'https://api.alttext.io/getmetadata',
    headers={'Content-Type': 'application/json'},
    json={
        'apikey': 'your_api_key_here',
        'fileurl': 'https://example.com/image.jpg',
        'keyword': 'office productivity',
        'language': 'english',
        'mode': 'seo'
    }
)

if response.status_code == 200:
    metadata = response.json()
    print(metadata[0]['title'])
    print(metadata[0]['alttext'])
else:
    print('Error:', response.json()['error'])

SEO mode vs. stock mode

SEO mode generates keyword-optimized metadata for search engines and requires a keyword parameter. Uses 1 credit.

Stock mode returns a buyer-focused title, layered description, alt text, and ~35 comma-separated keywords. The keyword parameter is ignored. Uses 2 credits.

Supported languages

English, Spanish, French, German, Italian, Portuguese, Dutch, Russian, Chinese, Japanese, Korean, and Arabic. Pass the lowercase language name in the language parameter; it defaults to english.

Errors, credits & limits

Error responses

Errors return a JSON object with an error message. Common cases (all HTTP 400): invalid JSON input, missing API key, missing file URL, missing keyword for SEO optimization, invalid API key, and insufficient credits. 

{ "error": "Invalid API key" }

Credits & rate limits

Each successful request consumes credits: 1 in SEO mode, 2 in stock mode. Failed requests are not charged.

Requests are limited to 60 per minute and 1,000 per hour. Exceeding the limit returns a 429 (Too Many Requests) response.

Ready to start building?

Get your API key and start generating SEO-optimized metadata programmatically.

Get API key View pricing

60 requests/minute • 1,000 requests/hour