Base URL

txt
https://api.altextapi.com/v1

All requests must include your API key in the X-API-Key header.

Authentication

POST/v1/validate-key

Validate your API key and get account information.

Request Body

txt
{
  "api_key": "alt_YOUR_API_KEY"
}

Response

txt
{
  "valid": true,
  "plan": "free",
  "credits_total": 50,
  "credits_used": 12,
  "credits_remaining": 38
}

Generate Alt Text

POST/v1/alt-text🔑 API Key

Generate alt text for a single image URL.

Request Body

txt
{
  "image_url": "https://example.com/photo.jpg",
  "language": "en",
  "context": "Product photo for ecommerce listing",
  "max_length": 125
}

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | image_url | string | Yes | Public URL of the image to describe | | language | string | No | ISO 639-1 language code (default: en) | | context | string | No | Additional context about the image | | max_length | integer | No | Maximum characters for alt text (default: 125) |

Response

txt
{
  "alt_text": "A modern ergonomic office chair with black mesh back and adjustable armrests against a white background.",
  "credits_remaining": 37,
  "wcag_compliant": true,
  "character_count": 118,
  "processing_time_ms": 1520
}

Rate Limits

Free tier: 5 requests/minute. Pro: 20 requests/minute. Business: 60 requests/minute. Agency: 120 requests/minute.

Check Usage

GET/v1/usage🔑 API Key

Get current plan, credit usage, and account status.

Response

txt
{
  "plan": "pro",
  "billing_period": {
    "start": "2026-07-01T00:00:00Z",
    "end": "2026-08-01T00:00:00Z"
  },
  "credits": {
    "total": 1000,
    "used": 342,
    "remaining": 658
  },
  "api_calls_today": 47
}

Error Codes

| Status | Code | Description | |--------|------|-------------| | 400 | invalid_request | Missing or malformed request body | | 401 | unauthorized | Invalid or missing API key | | 402 | insufficient_credits | No credits remaining | | 403 | plan_restricted | Feature not available on your plan | | 404 | not_found | Resource not found | | 429 | rate_limited | Too many requests | | 500 | internal_error | Server error — try again later |

All errors return:

txt
{
  "error": {
    "code": "invalid_request",
    "message": "The 'image_url' field is required.",
    "docs": "https://altextapi.com/docs/api-reference/errors"
  }
}

Always check credits

Poll /v1/usage before bulk operations to avoid insufficient_credits errors mid-batch. The credits_remaining field in alt-text responses is for convenience — it may be slightly stale.