Files
Quote-Generator/README.md

846 lines
24 KiB
Markdown

# Quote Generator API
Generate Twitter-style quote images programmatically. Perfect for creating social media content, screenshots, or fake tweets.
**Base URL:** `https://quotes.imbenji.net`
## Features
- Twitter-authentic styling
- Support for images, videos, GIFs, and text-only tweets
- Verified badge (blue checkmark)
- Engagement metrics (likes, retweets, replies, views)
- High-resolution output (3240x3240)
- Built-in caching (24-hour TTL)
- Base64 image support
- Video/GIF rendering with Playwright (v2 API only)
- Background video processing with status tracking
- Docker-ready
- v2 API with stateful sessions for incremental updates
- Persistent snapshot links (48-hour TTL, immutable, shareable)
## API Endpoints
### POST /generate
Generate a quote image using JSON request body.
**Request:**
```bash
curl -X POST https://quotes.imbenji.net/generate \
-H "Content-Type: application/json" \
-d '{
"displayName": "Geoff Marshall",
"username": "@geofftech",
"avatarUrl": "https://example.com/avatar.jpg",
"text": "Does anyone else find it immensely satisfying when you turn a pocket inside out and get rid of the crumbs and fluff stuck in the bottom.",
"timestamp": 1499766270
}' --output quote.png
```
### GET /generate
Generate a quote image using query parameters.
**Request:**
```bash
curl "https://quotes.imbenji.net/generate?displayName=John%20Doe&username=@johndoe&text=Hello%20World&timestamp=1735574400" --output quote.png
```
## Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `displayName` | string | No | Display name (defaults to "Anonymous") |
| `username` | string | No | Twitter handle with @ (defaults to "@anonymous") |
| `avatarUrl` | string | No | Avatar image URL or base64 data URI |
| `text` | string | No | Tweet text content |
| `imageUrl` | string | No | Tweet image URL, base64 data URI, or `null` |
| `timestamp` | integer | No | Unix epoch timestamp in seconds |
| `verified` | boolean | No | Show verified badge (blue checkmark) next to name |
| `engagement` | object | No | Engagement metrics (likes, retweets, replies, views) |
## Response
- **Content-Type:** `image/png`
- **Headers:**
- `X-Cache`: `HIT` (served from cache) or `MISS` (newly generated)
## Examples
### Text-only tweet
```javascript
fetch('https://quotes.imbenji.net/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'John Doe',
username: '@johndoe',
text: 'Just deployed my new API!',
timestamp: Math.floor(Date.now() / 1000)
})
})
.then(res => res.blob())
.then(blob => {
const url = URL.createObjectURL(blob);
document.getElementById('img').src = url;
});
```
### Tweet with image
```javascript
const response = await fetch('https://quotes.imbenji.net/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Jane Smith',
username: '@janesmith',
avatarUrl: 'https://example.com/avatar.jpg',
text: 'Check out this amazing view! 🌄',
imageUrl: 'https://example.com/photo.jpg',
timestamp: 1735574400
})
});
const blob = await response.blob();
// Save or display the image
```
### Using base64 images
```javascript
fetch('https://quotes.imbenji.net/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Alice',
username: '@alice',
avatarUrl: 'data:image/png;base64,iVBORw0KGgo...',
text: 'Using base64 images works too!',
imageUrl: 'data:image/jpeg;base64,/9j/4AAQSkZJ...',
timestamp: 1735574400
})
});
```
### Python example
```python
import requests
import time
response = requests.post('https://quotes.imbenji.net/generate', json={
'displayName': 'Python User',
'username': '@pythonista',
'text': 'Making API calls with Python!',
'timestamp': int(time.time())
})
with open('quote.png', 'wb') as f:
f.write(response.content)
```
### cURL with GET
```bash
curl -G "https://quotes.imbenji.net/generate" \
--data-urlencode "displayName=Test User" \
--data-urlencode "username=@testuser" \
--data-urlencode "text=This is a test tweet" \
--data-urlencode "timestamp=1735574400" \
--output quote.png
```
### Verified badge
```javascript
fetch('https://quotes.imbenji.net/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Elon Musk',
username: '@elonmusk',
text: 'Just bought Twitter!',
verified: true,
timestamp: 1735574400
})
});
```
### Engagement metrics
```javascript
fetch('https://quotes.imbenji.net/generate', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Popular User',
username: '@viral',
text: 'This tweet went viral!',
verified: true,
engagement: {
replies: 1234,
retweets: 5678,
likes: 98765,
views: 1500000
},
timestamp: 1735574400
})
});
```
**Note:** All four engagement fields (replies, retweets, likes, views) must be provided for the engagement bar to appear. Numbers are automatically formatted (e.g., 1234 → 1.2K, 1500000 → 1.5M).
---
## v2 API (Stateful Sessions)
The v2 API lets you build quote images incrementally. Instead of sending everything in one request, you create a session and update fields as needed. This is more efficient when making multiple edits since you dont need to resend large images every time.
### How it works
1. Create a session with `POST /v2/quote`
2. Update fields with `PATCH /v2/quote/:id` (only send whats changed)
3. Render the image with `GET /v2/quote/:id/image`
Sessions expire after 24 hours of inactivity.
### Video/GIF Support (v2 Only)
The v2 API supports video and animated GIF rendering. When you provide a video or GIF in the `imageUrl` parameter, the API automatically:
- Detects the video format (MP4, WebM, MOV, GIF)
- Renders the video in the background using Playwright
- Returns an animated MP4 file showing the video playing within the tweet frame
- Tracks render status (`pending`, `rendering`, `completed`, `failed`)
**Supported formats:**
- MP4 (H.264, H.265)
- WebM (VP8, VP9)
- MOV (QuickTime)
- GIF (animated, converted to MP4)
**Note:** Video rendering happens asynchronously in the background. The `GET /v2/quote/:id/image` endpoint will wait (up to 15 minutes) for the render to complete before returning the video file.
### POST /v2/quote
Create a new session.
**Request:**
```bash
curl -X POST https://quotes.imbenji.net/v2/quote \
-H "Content-Type: application/json" \
-d '{
"displayName": "John Doe",
"username": "@johndoe",
"text": "Hello world"
}'
```
**Response (201):**
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"displayName": "John Doe",
"username": "@johndoe",
"text": "Hello world",
"avatarUrl": null,
"imageUrl": null,
"timestamp": null,
"verified": false,
"engagement": null,
"renderStatus": "completed",
"renderProgress": 100,
"renderPid": null,
"renderError": null,
"createdAt": 1735600000,
"updatedAt": 1735600000
}
```
**Render Status Fields:**
- `renderStatus`: Current render state (`pending`, `rendering`, `completed`, `failed`)
- `renderProgress`: Render progress percentage (0-100)
- `renderPid`: Process ID of background render (only present during `rendering`)
- `renderError`: Error message if `renderStatus` is `failed`
### GET /v2/quote/:id
Get current session state.
```bash
curl https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```
### PATCH /v2/quote/:id
Update specific fields. Only send the fields you want to change.
```bash
curl -X PATCH https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Content-Type: application/json" \
-d '{
"text": "Updated text!",
"avatarUrl": "data:image/png;base64,..."
}'
```
**Engagement updates:**
```bash
# Set all engagement metrics
curl -X PATCH https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Content-Type: application/json" \
-d '{
"engagement": {
"replies": 100,
"retweets": 250,
"likes": 5000,
"views": 50000
}
}'
# Partial update (update only likes, keep other fields)
curl -X PATCH https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Content-Type: application/json" \
-d '{
"engagement": {
"likes": 10000
}
}'
# Clear engagement entirely (removes engagement bar)
curl -X PATCH https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Content-Type: application/json" \
-d '{
"engagement": null
}'
```
**Verified badge:**
```bash
# Add verified badge
curl -X PATCH https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Content-Type: application/json" \
-d '{
"verified": true
}'
```
### GET /v2/quote/:id/render-info
Get real-time render progress via Server-Sent Events (SSE).
```bash
curl -N https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890/render-info
```
**Response (text/event-stream):**
```
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":0,"stage":"rendering","error":null}
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":25,"stage":"rendering","error":null}
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":50,"stage":"rendering","error":null}
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":99,"stage":"rendering","error":null}
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":0,"stage":"encoding","error":null}
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":50,"stage":"encoding","error":null}
data: {"status":"rendering","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":99,"stage":"encoding","error":null}
data: {"status":"completed","sessionId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","progress":100,"stage":"completed","error":null}
```
**JavaScript Example:**
```javascript
const eventSource = new EventSource(
`https://quotes.imbenji.net/v2/quote/${sessionId}/render-info`
);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(`Render: ${data.stage} (${data.progress}%)`);
// Update progress bar and stage label in UI
document.getElementById('progress-bar').style.width = `${data.progress}%`;
document.getElementById('progress-text').textContent = `${data.progress}%`;
// Show current stage
let stageText = '';
if (data.stage === 'rendering') {
stageText = 'Rendering video...';
} else if (data.stage === 'encoding') {
stageText = 'Encoding to H.264...';
} else if (data.stage === 'completed') {
stageText = 'Complete!';
}
document.getElementById('stage-label').textContent = stageText;
if (data.status === 'completed') {
console.log('Render complete! Fetching video...');
eventSource.close();
// Now fetch the video
fetch(`https://quotes.imbenji.net/v2/quote/${sessionId}/image`)
.then(res => res.blob())
.then(blob => {
// Handle the video blob
});
} else if (data.status === 'failed') {
console.error('Render failed:', data.error);
eventSource.close();
}
};
eventSource.onerror = (error) => {
console.error('SSE error:', error);
eventSource.close();
};
```
**Status values:**
- `pending` - Render queued but not started (progress: 0%)
- `rendering` - In progress (progress: 0-99%)
- `completed` - Successfully rendered (progress: 100%)
- `failed` - Render failed (check `error` field)
- `deleted` - Session was deleted
**Response fields:**
- `status` - Current render status (`pending`, `rendering`, `completed`, `failed`)
- `sessionId` - Session identifier
- `progress` - Current stage completion percentage (0-100)
- `stage` - Current render stage (`idle`, `rendering`, `encoding`, `completed`, `failed`)
- `error` - Error message (only present if status is `failed`)
**Render Stages:**
1. **rendering** - Recording video with Playwright (progress 0-99%)
2. **encoding** - Converting to H.264 MP4 with FFmpeg (progress 0-99%)
3. **completed** - Render finished successfully (progress 100%)
**Notes:**
- The stream automatically closes when render is `completed` or `failed`
- Progress updates are sent every 200ms while render is in progress
- Progress resets to 0% when transitioning between stages (rendering → encoding)
- Each stage reports its own progress percentage independently
- Use the `stage` field to show different messages in your UI
### GET /v2/quote/:id/image
Render the current session state as an image or video.
```bash
# For images
curl https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890/image --output quote.png
# For videos
curl https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890/image --output quote.mp4
```
**Response headers:**
- `Content-Type: image/png` (for images) or `video/mp4` (for videos)
- `X-Session-Id: <session-id>`
- `X-Cache: HIT` or `MISS`
**Notes:**
- For video renders, this endpoint will wait up to 15 minutes for the background render to complete
- If the render is still in progress, the response will be delayed (polling internally)
- If the render fails, a 500 error will be returned with details
- If the render times out, a 504 error will be returned
- For better UX, use `/render-info` to track progress and only call this when complete
### DELETE /v2/quote/:id
Delete a session.
```bash
curl -X DELETE https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```
Returns `204 No Content` on success.
### POST /v2/quote/:id/snapshot-link
Create a persistent snapshot link. This captures the current state of your session and generates a shareable URL that persists for 48 hours (refreshing on each access).
Unlike the regular `/image` endpoint, snapshots are immutable - they always show the image as it was when the snapshot was created, even if you update the session afterwards.
**Request:**
```bash
curl -X POST https://quotes.imbenji.net/v2/quote/a1b2c3d4-e5f6-7890-abcd-ef1234567890/snapshot-link
```
**Response (201):**
```json
{
"token": "xY9pQmN3kL8vFw2jRtZ7",
"url": "https://quotes.imbenji.net/v2/snapshot/xY9pQmN3kL8vFw2jRtZ7",
"sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"createdAt": 1735600000,
"expiresAt": 1735772800
}
```
### GET /v2/snapshot/:token
Retrieve a snapshot image using its token.
```bash
curl https://quotes.imbenji.net/v2/snapshot/xY9pQmN3kL8vFw2jRtZ7 --output snapshot.png
```
**Response headers:**
- `Content-Type: image/png`
- `X-Snapshot-Token: <token>`
- `X-Cache: HIT` or `MISS`
**Snapshot behavior:**
- **Immutable:** Shows the session state when the snapshot was created
- **TTL:** 48 hours from last access (resets on each view)
- **Cascade delete:** Deleted automatically when parent session is deleted
- **Shareable:** Token can be shared with anyone
### v2 Example Workflow
```javascript
// 1. Create session with initial data
const res = await fetch('https://quotes.imbenji.net/v2/quote', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Jane Doe',
username: '@janedoe',
text: 'Working on something cool'
})
});
const session = await res.json();
const sessionId = session.id;
// 2. Later, add an avatar (only sends the avatar, not everything again)
await fetch(`https://quotes.imbenji.net/v2/quote/${sessionId}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
avatarUrl: 'data:image/png;base64,iVBORw0KGgo...'
})
});
// 3. Update the text
await fetch(`https://quotes.imbenji.net/v2/quote/${sessionId}`, {
method: 'PATCH',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
text: 'Finished building something cool!'
})
});
// 4. Generate the final image
const imgRes = await fetch(`https://quotes.imbenji.net/v2/quote/${sessionId}/image`);
const blob = await imgRes.blob();
// 5. (Optional) Create a shareable snapshot link
const snapshotRes = await fetch(`https://quotes.imbenji.net/v2/quote/${sessionId}/snapshot-link`, {
method: 'POST'
});
const snapshot = await snapshotRes.json();
console.log('Shareable URL:', snapshot.url);
// Anyone can access: https://quotes.imbenji.net/v2/snapshot/<token>
```
### v2 Video Example
```javascript
// 1. Create session with video
const res = await fetch('https://quotes.imbenji.net/v2/quote', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Video Creator',
username: '@videocreator',
text: 'Check out this awesome clip!',
imageUrl: 'data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21...' // base64 video
})
});
const session = await res.json();
console.log('Render status:', session.renderStatus); // "rendering"
// 2. Track render progress with SSE (recommended)
const eventSource = new EventSource(
`https://quotes.imbenji.net/v2/quote/${session.id}/render-info`
);
eventSource.onmessage = async (event) => {
const data = JSON.parse(event.data);
console.log(`Render: ${data.status} (${data.progress}%)`);
// Update UI with progress
if (data.status === 'rendering') {
// Show progress bar: 0% -> 99%
updateProgressBar(data.progress);
}
if (data.status === 'completed') {
eventSource.close();
updateProgressBar(100);
// 3. Get the rendered video
const videoRes = await fetch(`https://quotes.imbenji.net/v2/quote/${session.id}/image`);
const videoBlob = await videoRes.blob();
console.log('Content-Type:', videoRes.headers.get('Content-Type')); // "video/mp4"
// Save the video
const url = URL.createObjectURL(videoBlob);
const a = document.createElement('a');
a.href = url;
a.download = 'quote-video.mp4';
a.click();
} else if (data.status === 'failed') {
console.error('Render failed:', data.error);
eventSource.close();
}
};
// Alternative: Simple approach (blocks until complete)
// const videoRes = await fetch(`https://quotes.imbenji.net/v2/quote/${session.id}/image`);
// const videoBlob = await videoRes.blob();
```
**GIF Example:**
```javascript
// Animated GIFs are automatically detected and rendered as MP4 videos
const res = await fetch('https://quotes.imbenji.net/v2/quote', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'GIF Lover',
username: '@giflover',
text: 'This GIF is fire 🔥',
imageUrl: 'data:image/gif;base64,R0lGODlhAQABAIAAAP...' // animated GIF
})
});
// The output will be an MP4 video file
```
**Full HTML Progress Bar Example:**
```html
<!DOCTYPE html>
<html>
<head>
<style>
.progress-container {
width: 100%;
background-color: #f0f0f0;
border-radius: 8px;
overflow: hidden;
}
.progress-bar {
height: 30px;
background-color: #4CAF50;
width: 0%;
transition: width 0.2s;
display: flex;
align-items: center;
justify-content: center;
color: white;
font-weight: bold;
}
</style>
</head>
<body>
<div class="progress-container">
<div class="progress-bar" id="progressBar">0%</div>
</div>
<video id="videoPlayer" controls style="display:none; margin-top:20px; width:100%;"></video>
<script>
async function renderVideo() {
// Create session with video
const res = await fetch('https://quotes.imbenji.net/v2/quote', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
displayName: 'Video Creator',
username: '@videocreator',
text: 'Check out this clip!',
imageUrl: 'data:video/mp4;base64,AAAAIGZ0eXBpc29t...'
})
});
const session = await res.json();
// Track progress with SSE
const eventSource = new EventSource(
`https://quotes.imbenji.net/v2/quote/${session.id}/render-info`
);
eventSource.onmessage = async (event) => {
const data = JSON.parse(event.data);
// Update progress bar
const progressBar = document.getElementById('progressBar');
progressBar.style.width = data.progress + '%';
progressBar.textContent = data.progress + '%';
if (data.status === 'completed') {
eventSource.close();
// Fetch and display video
const videoRes = await fetch(
`https://quotes.imbenji.net/v2/quote/${session.id}/image`
);
const blob = await videoRes.blob();
const url = URL.createObjectURL(blob);
const video = document.getElementById('videoPlayer');
video.src = url;
video.style.display = 'block';
} else if (data.status === 'failed') {
eventSource.close();
alert('Render failed: ' + data.error);
}
};
}
renderVideo();
</script>
</body>
</html>
```
### v2 Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `displayName` | string | Display name |
| `username` | string | Twitter handle with @ |
| `avatarUrl` | string | Avatar image URL or base64 |
| `text` | string | Tweet text content |
| `imageUrl` | string | Tweet image URL or base64 |
| `timestamp` | integer | Unix epoch in seconds |
| `verified` | boolean | Show verified badge (blue checkmark) |
| `engagement` | object/null | Engagement metrics (see below) |
**Engagement object:**
```json
{
"engagement": {
"replies": 89,
"retweets": 567,
"likes": 1234,
"views": 50000
}
}
```
**Engagement behavior:**
- All four fields must be provided for the engagement bar to appear
- Partial updates: Only update specific fields, others remain unchanged
- Set to `null` to clear all engagement and hide the engagement bar
- Numbers are auto-formatted (1234 → 1.2K, 1000000 → 1M)
---
## Caching
The API automatically caches generated images for 24 hours from the last request. Identical requests will be served from cache instantly.
- Cache hits include `X-Cache: HIT` header
- Cache misses include `X-Cache: MISS` header
- Cache is cleaned up hourly
- Images are stored based on SHA-256 hash of parameters
## Timestamp Format
The `timestamp` parameter expects a Unix epoch timestamp in **seconds** (not milliseconds).
**JavaScript:**
```javascript
const timestamp = Math.floor(Date.now() / 1000);
```
**Python:**
```python
import time
timestamp = int(time.time())
```
The timestamp will be formatted as: `5:58 PM · Dec 29, 2025`
## Default Avatar
If no `avatarUrl` is provided, a default Twitter-style placeholder avatar will be used.
## Rate Limiting
Currently, there are no rate limits. Please use responsibly.
## Self-Hosting
### Docker (Recommended)
```bash
git clone <repository>
cd quotegen
docker-compose up -d
```
The API will be available at `http://localhost:3000`
### Manual Setup
```bash
npm install
npx playwright install chromium
npm start
```
**Note:** Video rendering requires Playwright and FFmpeg. The Docker setup handles this automatically.
## Health Check
```bash
curl https://quotes.imbenji.net/health
```
Response:
```json
{
"status": "ok"
}
```
## Technical Details
- **Resolution:** 3240x3240 (1:1 aspect ratio) for images, 1500x1500 for videos
- **Format:** PNG (images), MP4 (videos)
- **Max tweet width:** 450px (auto-scaled to fit)
- **Cache TTL:** 24 hours from last access
- **Session TTL:** 24 hours from last update (v2 API)
- **Snapshot TTL:** 48 hours from last access (v2 API)
- **Cleanup interval:** Every hour
- **Database:** SQLite (for v2 sessions and snapshots)
- **Video rendering:** Playwright Chromium with background worker processes
- **Video timeout:** 15 minutes maximum render time
- **Supported video formats:** MP4, WebM, MOV, GIF
## Limitations
- Tweet text is not wrapped intelligently (use `\n` for line breaks if needed)
- Very long tweets may be cut off
- External image URLs must be publicly accessible
- Base64 images should be reasonably sized
- Video rendering is only available in v2 API (not in `/generate` endpoint)
- Video renders can take several seconds depending on video duration
- Very long videos (>15 minutes) may timeout
- Video audio is muted in the output
## Support
For issues or questions, please contact the maintainer.
---
**Built with:** Node.js, Express, Puppeteer, Playwright, SQLite, FFmpeg