# Image Render API - API Documentation ## Overview The Image Render API provides powerful image processing capabilities, allowing you to resize images from URLs or base64 data, and render HTML templates directly into images. Perfect for generating thumbnails, creating social media images, or converting web content to images. ## Base URL ``` https://your-api-domain.com ``` ## Authentication This API uses header-based authentication. Include your API key in the request headers: ``` X-API-Key: your-api-key-here ``` **Note:** All endpoints except `/` require authentication. Requests without a valid API key will receive a `403 Forbidden` response. ## Endpoints ### 1. Resize Image Resize images from a URL or base64-encoded data with optional cropping options. **Endpoint:** `POST /resize` **Request Body:** | Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------------------------------------------------------------------------------- | | `url` | string | No\* | URL of the image to resize | | `base64` | string | No\* | Base64-encoded image data | | `width` | integer | No | Target width in pixels. If omitted, calculated from height maintaining aspect ratio | | `height` | integer | No | Target height in pixels | | `crop` | string | No | Cropping method: `center`, `top`, `bottom`, `left`, `right` | | `output` | string | No | Output format: `jpg` or `png` (default: `jpg`) | \*Either `url` or `base64` must be provided, but not both. **Response:** Returns the resized image as binary data with appropriate content-type (`image/jpeg` or `image/png`). **Example Request:** ```json { "url": "https://example.com/image.jpg", "width": 800, "height": 600, "crop": "center", "output": "jpg" } ``` **Example Response:** Binary image data (Content-Type: `image/jpeg`) **cURL Example:** ```bash curl -X POST "https://your-api-domain.com/resize" \ -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/image.jpg", "width": 800, "height": 600, "crop": "center", "output": "jpg" }' \ --output resized_image.jpg ``` **JavaScript Example:** ```javascript const response = await fetch("https://your-api-domain.com/resize", { method: "POST", headers: { "X-API-Key": "your-api-key", "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://example.com/image.jpg", width: 800, height: 600, crop: "center", output: "jpg", }), }); const blob = await response.blob(); // Use the blob (e.g., create an image element or save to file) ``` **Python Example:** ```python import requests url = "https://your-api-domain.com/resize" headers = { "X-API-Key": "your-api-key", "Content-Type": "application/json" } data = { "url": "https://example.com/image.jpg", "width": 800, "height": 600, "crop": "center", "output": "jpg" } response = requests.post(url, json=data, headers=headers) if response.status_code == 200: with open("resized_image.jpg", "wb") as f: f.write(response.content) ``` ### 2. Render HTML Template Convert HTML templates directly into images. Perfect for generating social media graphics, certificates, or any custom image content. **Endpoint:** `POST /template` **Request Body:** | Parameter | Type | Required | Description | | --------- | ------- | -------- | ------------------------------------------------------ | | `html` | string | Yes | HTML template to render | | `width` | integer | No | Width of the rendered image in pixels (default: 1920) | | `height` | integer | No | Height of the rendered image in pixels (default: 1080) | | `output` | string | No | Output format: `jpg` or `png` (default: `jpg`) | **Response:** Returns the rendered image as binary data with appropriate content-type (`image/jpeg` or `image/png`). **Example Request:** ```json { "html": "<html><body style='background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; font-family: Arial; padding: 50px;'>

Hello World

This is a rendered HTML template

</body></html>", "width": 1920, "height": 1080, "output": "png" } ``` **Example Response:** Binary image data (Content-Type: `image/png`) **cURL Example:** ```bash curl -X POST "https://your-api-domain.com/template" \ -H "X-API-Key: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "html": "<html><body>

Hello World

</body></html>", "width": 1920, "height": 1080, "output": "png" }' \ --output rendered_template.png ``` **JavaScript Example:** ```javascript const response = await fetch("https://your-api-domain.com/template", { method: "POST", headers: { "X-API-Key": "your-api-key", "Content-Type": "application/json", }, body: JSON.stringify({ html: "<html><body>

Hello World

</body></html>", width: 1920, height: 1080, output: "png", }), }); const blob = await response.blob(); // Use the blob ``` **Python Example:** ```python import requests url = "https://your-api-domain.com/template" headers = { "X-API-Key": "your-api-key", "Content-Type": "application/json" } data = { "html": "<html><body>

Hello World

</body></html>", "width": 1920, "height": 1080, "output": "png" } response = requests.post(url, json=data, headers=headers) if response.status_code == 200: with open("rendered_template.png", "wb") as f: f.write(response.content) ``` ## Error Responses ### 400 Bad Request Returned when request parameters are invalid or missing. ```json { "detail": "Entweder 'url' oder 'base64' muss angegeben sein" } ``` ### 403 Forbidden Returned when authentication fails or API key is missing/invalid. ```json { "detail": "Forbidden" } ``` ### 500 Internal Server Error Returned when an unexpected server error occurs. ```json { "detail": "Fehler beim Rendern des HTML Templates: [error message]" } ``` ## Use Cases ### 1. Thumbnail Generation Generate thumbnails from full-size images for galleries or listings. ### 2. Social Media Graphics Create custom social media images from HTML templates with dynamic content. ### 3. Image Optimization Resize images to specific dimensions for web optimization. ### 4. Certificate Generation Generate certificates or documents from HTML templates. ### 5. Image Cropping Crop images to specific aspect ratios for different use cases. ## Best Practices 1. **Image Formats**: Use `png` for images with transparency, `jpg` for photos 2. **Aspect Ratios**: When resizing, specify both width and height for precise control, or use cropping for specific aspect ratios 3. **HTML Templates**: Keep HTML templates simple and self-contained. External resources may not load correctly 4. **Base64 Images**: For base64 input, you can include the data URL prefix (`data:image/png;base64,`) or just the base64 string 5. **Error Handling**: Always check response status codes and handle errors appropriately ## Rate Limits Rate limits may apply based on your subscription plan. Check your API dashboard for current limits. ## Support For support, please contact [support email] or visit [support documentation URL].