How do I use the imghero API?

The imghero API lets you generate images programmatically. API access requires a Pro plan.

Authentication

Include your API token in the Authorization header:

Authorization: Token YOUR_API_TOKEN

Get your API token from your Account page.

Generate an Image

POST /api/v1/generate/

Kick off image generation for a URL. Returns immediately with a predictable image URL.

Request

curl -X POST https://img-hero.com/api/v1/generate/ \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/my-post"
  }'

Parameters

Response

{
  "url_id": "url_abc12345",
  "image_url": "https://img-hero.com/img/url_abc12345/",
  "status": "generating"
}

The image_url is a stable URL you can use immediately. It will return 404 until generation completes (typically 10-30 seconds), then redirect to the generated image.

Search Your URLs

GET /api/v1/urls/

List all URLs you’ve generated images for, with optional search.

Request

curl "https://img-hero.com/api/v1/urls/?q=blog&limit=10" \
  -H "Authorization: Token YOUR_API_TOKEN"

Parameters

Response

{
  "urls": [
    {
      "url_id": "url_abc12345",
      "url": "https://example.com/blog/my-post",
      "title": "My Blog Post",
      "image_url": "https://img-hero.com/img/url_abc12345/",
      "images": [
        {
          "image_id": "img_xyz789",
          "style": "photo",
          "text_treatment": "none",
          "status": "completed",
          "created_at": "2024-01-15T10:30:00Z",
          "direct_url": "https://storage.example.com/generated/..."
        }
      ],
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Get URL Details

GET /api/v1/urls/{url_id}/

Get details for a specific URL including all generated images.

curl https://img-hero.com/api/v1/urls/url_abc12345/ \
  -H "Authorization: Token YOUR_API_TOKEN"

Returns the same structure as a single item from the search response.

Rate Limits

• 100 requests per minute per user
• Each generation request consumes 1 image from your balance

Error Codes