External API for Alt Text Generation

Overview

This API endpoint allows external ecommerce tools (Shopify apps, WooCommerce plugins, Magento extensions, etc.) to generate SEO-optimized alt text for product images.

Authentication

API uses Laravel Sanctum token-based authentication.

How to Get Your API Key

1. Sign up/Login: Visit the dashboard at https://your-domain.com/dashboard
2. Generate API Key:
   • Scroll down to the "API Keys" section
   • Enter a name for your token (e.g., "Shopify Store", "WooCommerce Site")
   • Click "Generate API Key"
   • Important: Copy the token immediately - you won't be able to see it again!
3. Use the Token: Include it in the Authorization header as Bearer YOUR_TOKEN

API Key Management

• Maximum 5 API keys per user
• Keys can be deleted anytime from the dashboard
• Track usage and last used date for each key
• Keys never expire but can be revoked

Endpoints

Test Credentials

GET /api/v1/test-credentials

This endpoint allows you to verify your API key is valid and check your account status without consuming credits.

Headers:

Authorization: Bearer {API_TOKEN}
Accept: application/json

Request Body:

None required.

Response (Success):

{
  "success": true,
  "message": "API credentials are valid",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "credits": {
      "available": 500,
      "can_generate": true
    },
    "subscription": {
      "plan": "Professional",
      "monthly_credits": 500,
      "credits_used": 0,
      "status": "active"
    }
  }
}

Response (Error - Invalid API Key):

{
  "success": false,
  "message": "Invalid API key"
}

cURL Example:

curl -X GET https://your-domain.com/api/v1/test-credentials \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

---

Generate Alt Text

POST /api/v1/generate-alt-text

Headers:

Authorization: Bearer {API_TOKEN}
Content-Type: application/json
Accept: application/json

Request Body:

{
  "image_url": "https://example.com/path/to/image.jpg",
  "context": "Blue cotton t-shirt with vintage logo, size medium, casual wear",
  "language": "English"
}

Parameters:

• image_url (required): Direct URL to the image. Supports both external URLs and local development URLs (localhost, 127.0.0.1, .local domains)
• context (optional): Product description or context to improve alt text generation
• language (optional): Language for alt text generation. Supported languages: English, Spanish, French, Portuguese, German, Italian, Russian, Japanese, Korean, Chinese, Arabic, Hindi, Dutch, Swedish, Danish, Norwegian, Finnish, Polish, Czech, Hungarian, Turkish, Hebrew, Thai, Vietnamese. Defaults to "English".

Response (Success):

{
  "success": true,
  "data": {
    "id": 123,
    "image_url": "https://example.com/path/to/image.jpg",
    "generated_alt": "Blue cotton t-shirt with vintage logo displayed on white background",
    "image_width": 800,
    "image_height": 600,
    "credits_remaining": 487,
    "language": "English"
  }
}

Response (Error - Invalid API Key):

{
  "success": false,
  "message": "Invalid API key"
}

Response (Error - Insufficient Credits):

{
  "success": false,
  "message": "Insufficient credits. Please upgrade your plan.",
  "credits_remaining": 0
}

Response (Error - Validation Failed):

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "image_url": ["The image url field is required."]
  }
}

Usage Examples

cURL Example

curl -X POST https://your-domain.com/api/v1/generate-alt-text \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/product-image.jpg",
    "context": "Premium leather handbag, brown color, suitable for office and casual use",
    "language": "English"
  }'

Rate Limits

• Rate limiting is based on user credits
• Each successful generation consumes 1 credit
• Failed requests do not consume credits

Best Practices

1. Include Context: Provide product descriptions, brand names, colors, materials for better alt text generation.
2. Image URLs: Ensure image URLs are publicly accessible and return valid image content.
3. Error Handling: Always check the success field and handle errors appropriately.
4. Credit Management: Monitor credits_remaining in responses to avoid service interruptions.
5. Language Selection: Use appropriate language settings for international stores.

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• GIF (.gif)
• SVG (.svg)

Technical Notes

• Maximum image size: 10MB
• Timeout: 30 seconds
• Context text limit: 1000 characters
• Generated alt text is optimized for accessibility and SEO
• Alt text follows WCAG guidelines and avoids phrases like "image of" or "picture of"
• Local URL Support: Local development URLs (localhost, 127.0.0.1, .local) are automatically converted to base64 data URLs for OpenAI processing