Signed URLs API

Generate secure, time-limited URLs for direct image access without exposing your API key.

Overview

Signed URLs allow you to:

• Share direct links to generated images
• Embed images in emails and external sites
• Avoid exposing your API key in client-side code
• Set expiration times for temporary access

Generate Signed URL

Endpoint

GET /api/signed/generate

Query Parameters

Parameter	Type	Required	Description
title	string	Yes	Main headline
subtitle	string	No	Secondary text
template	string	No	Template name
theme	string	No	Theme (dark/light)
expires_in	number	No	Expiration in seconds (default: 86400)

Authentication

Requires API key in X-API-Key header.

Response

{
  "url": "https://ogimageapi.io/api/signed/image?title=Hello&sig=abc123&exp=1699999999",
  "expires_at": "2024-11-14T12:00:00Z"
}

Access Signed Image

Endpoint

GET /api/signed/image

Query Parameters

The URL includes:

• All image parameters (title, subtitle, etc.)
• sig — Cryptographic signature
• exp — Expiration timestamp

No authentication required — the signature validates the request.

Response

Returns the generated image as image/png.

Example Usage

Generate a Signed URL

curl "https://ogimageapi.io/api/signed/generate?title=Hello+World&template=default&theme=dark" \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "url": "https://ogimageapi.io/api/signed/image?title=Hello+World&template=default&theme=dark&sig=a1b2c3d4e5&exp=1699999999",
  "expires_at": "2024-11-14T12:00:00Z"
}

Use the Signed URL

The returned URL can be used directly:

<meta property="og:image" content="https://ogimageapi.io/api/signed/image?title=Hello+World&sig=a1b2c3d4e5&exp=1699999999">

Or in an <img> tag:

<img src="https://ogimageapi.io/api/signed/image?title=Hello+World&sig=a1b2c3d4e5&exp=1699999999" alt="Preview">

Node.js Example

async function getSignedImageUrl(params) {
  const queryString = new URLSearchParams(params).toString();
  
  const response = await fetch(
    `https://ogimageapi.io/api/signed/generate?${queryString}`,
    {
      headers: {
        'X-API-Key': process.env.OG_IMAGE_API_KEY
      }
    }
  );
  
  const data = await response.json();
  return data.url;
}

// Usage
const imageUrl = await getSignedImageUrl({
  title: 'My Blog Post',
  subtitle: 'A great article about coding',
  template: 'blog',
  theme: 'dark',
  expires_in: 3600 // 1 hour
});

console.log(imageUrl);

Python Example

import requests
import os

def get_signed_image_url(params):
    response = requests.get(
        'https://ogimageapi.io/api/signed/generate',
        params=params,
        headers={'X-API-Key': os.environ['OG_IMAGE_API_KEY']}
    )
    return response.json()['url']

# Usage
url = get_signed_image_url({
    'title': 'My Blog Post',
    'subtitle': 'A great article',
    'template': 'blog',
    'expires_in': 3600
})
print(url)

Security Considerations

1. Expiration — Always set appropriate expiration times
2. Signature validation — Signatures are verified server-side
3. No API key exposure — Client-side code never sees your API key
4. HTTPS only — All signed URLs use HTTPS

Expiration Guidelines

Use Case	Recommended Expiration
Email images	7 days (604800 seconds)
Social shares	24 hours (86400 seconds)
Temporary previews	1 hour (3600 seconds)
Permanent content	30 days (2592000 seconds)

Error Handling

Error	Cause	Solution
401 Unauthorized	Invalid or missing API key	Check your API key
400 Signature invalid	Tampered URL or wrong signature	Use the exact URL returned
400 URL expired	Expiration time passed	Generate a new signed URL