How do I use the imghero API?

Q: How do I use the imghero API?

Generate images programmatically using the imghero REST 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

Field	Default	Description
url	required	The URL to generate an image for
style	“auto”	Visual style: auto, photo, illustration, sketch, neon_geo, cartoon, pop_art, isometric, minimal, 3d_render, cinematic, watercolor, line_art, retro, anime, paper_cut
format	“blog_hero”	Output format: blog_hero, square, banner_text, split_layout
mode	“lightning”	Generation mode: “lightning” (1 credit) or “premium” (10 credits)

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

Field	Default	Description
q		Search query (searches URL and title)
limit	20	Number of results (max 100)
offset	0	Pagination offset

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",
          "format": "blog_hero",
          "mode": "lightning",
          "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 credits based on mode (1 for lightning, 10 for premium)

Error Codes

Code	Meaning
401	Invalid or missing API token
402	Insufficient credits
403	API requires Pro plan
400	Invalid request parameters
404	URL not found
429	Rate limit exceeded