# Social Renders API - Quick Reference

Generate social media post screenshots (Twitter/X, Reddit, Threads, LinkedIn) as PNG images.

**Base URL**: `https://api.socialrenders.com`

## Authentication

Required for all endpoints:

```
Authorization: Bearer YOUR_API_KEY
```

API keys start with `sk_live_`. Supabase JWT tokens also accepted.

## Endpoints

### POST /generate

Generates image and uploads to R2 storage. Returns JSON with hosted image URL.

**Request**:
```json
{
  "templateId": "twitter-post",
  "fields": {
    "displayName": "John Doe",
    "username": "@johndoe",
    "tweetText": "Your tweet text here",
    "timestamp": "2h",
    "replyCount": "42",
    "repostCount": "15",
    "likeCount": "123",
    "viewCount": "1.7K",
    "isVerified": true,
    "hasBookmark": false,
    "avatarInitials": "JD",
    "profilePictureUrl": "https://example.com/avatar.jpg",
    "enableBackgroundColor": true,
    "backgroundColor": "#1a1a1a",
    "boxShadowAmount": 3
  }
}
```

**Response**: JSON
```json
{
  "imageUrl": "https://images.socialrenders.com/twitter-post-1234567890-abcdef.png",
  "width": 1200,
  "height": 628,
  "templateId": "twitter-post"
}
```

### POST /generate-preview

Returns raw PNG image buffer. Use for testing/previews. Same request format as `/generate`.

**Response**: PNG image binary (Content-Type: `image/png`)

**Errors**:
- `VALIDATION_ERROR` (400): Missing templateId or fields
- `INVALID_TEMPLATE` (400): Unknown template ID
- `UNAUTHORIZED` (401): Missing/invalid API key
- `PROCESSING_ERROR` (500): Rendering failed
- `UPLOAD_ERROR` (500): R2 upload failed (only /generate)

## Templates

All templates: 1200px width, flexible height (400-1200px). All fields optional with defaults.

### twitter-post

**Fields**:
- `displayName` (string): "John Doe"
- `username` (string): "@johndoe"
- `tweetText` (string): "Your tweet text here"
- `timestamp` (string): "2h" (relative time) or "Nov 13" (absolute date)
- `replyCount` (string): "42" or "1.2K"
- `repostCount` (string): "15" or "500"
- `likeCount` (string): "123" or "5.4K"
- `viewCount` (string): "1.7K" or "2M"
- `isVerified` (boolean): true
- `hasBookmark` (boolean): false
- `avatarInitials` (string): "JD"
- `profilePicture` (string): "data:image/png;base64,..."
- `profilePictureUrl` (string): "https://example.com/avatar.jpg" (fetches from URL, fallback to profilePicture then avatarInitials)
- `enableBackgroundColor` (boolean): true
- `backgroundColor` (string): "#1a1a1a"
- `boxShadowAmount` (number): 0-3 (0=none, 1=light/default, 2=medium, 3=strong). Only when enableBackgroundColor is true

### reddit-post

**Fields**:
- `displayName` (string): "displayname"
- `username` (string): "u/username"
- `title` (string): "Post title here"
- `content` (string): "Post body text here"
- `upvotes` (string): "10K+"
- `comments` (string): "99+"
- `isVerified` (boolean): false
- `enableBackgroundColor` (boolean): true
- `backgroundColor` (string): "#3e3e42"
- `boxShadowAmount` (number): 0-3. Only when enableBackgroundColor is true

### threads-post

**Fields**:
- `username` (string): "username"
- `content` (string): "Share something interesting..."
- `replies` (string): "0"
- `likes` (string): "0"
- `isVerified` (boolean): false
- `darkMode` (boolean): false
- `avatarInitials` (string): "GH"
- `profilePicture` (string): "data:image/png;base64,..."
- `profilePictureUrl` (string): "https://example.com/avatar.jpg"
- `enableBackgroundColor` (boolean): true
- `backgroundColor` (string): "#3e3e42"
- `boxShadowAmount` (number): 0-3. Only when enableBackgroundColor is true

### linkedin-post

**Fields**:
- `username` (string): "LinkedIn User"
- `headline` (string): "Professional Headline"
- `content` (string): "This is a LinkedIn post content."
- `timestamp` (string): "1h" or "2d"
- `likes` (string): "123"
- `comments` (string): "10"
- `reposts` (string): "5"
- `avatarInitials` (string): "LI"
- `profilePicture` (string): "data:image/png;base64,..."
- `profilePictureUrl` (string): "https://example.com/avatar.jpg"
- `enableBackgroundColor` (boolean): true
- `backgroundColor` (string): "#3e3e42"
- `boxShadowAmount` (number): 0-3. Only when enableBackgroundColor is true

## Common Features

**Profile Pictures** (twitter-post, threads-post, linkedin-post only):
- `profilePictureUrl`: Fetch from URL (recommended, 5MB max, 5s timeout)
- `profilePicture`: Base64 data URL (`data:image/png;base64,...`)
- `avatarInitials`: Fallback text initials (e.g., "JD")
Fallback order: profilePictureUrl → profilePicture → avatarInitials
Note: reddit-post always displays the Reddit logo and does not support profile pictures

**Background Colors**: Set `enableBackgroundColor: true` and `backgroundColor: "#hex"` to add colored padding. `false` returns transparent background.

**Box Shadow**: `boxShadowAmount` (0-3) controls shadow intensity when `enableBackgroundColor: true`. 0=none, 1=light (default), 2=medium, 3=strong

## Example Usage

```javascript
// /generate - Returns hosted image URL (recommended)
const response = await fetch('https://api.socialrenders.com/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: 'twitter-post',
    fields: {
      displayName: 'John Doe',
      username: '@johndoe',
      tweetText: 'This is my tweet!\n\nCheck it out! https://example.com\n\n#tech',
      timestamp: '2h',
      replyCount: '42',
      likeCount: '123',
      isVerified: true,
      profilePictureUrl: 'https://example.com/avatar.jpg',
      enableBackgroundColor: true,
      backgroundColor: '#1a1a1a',
      boxShadowAmount: 1
    }
  })
});

const data = await response.json();
// data = { imageUrl: "https://images.socialrenders.com/...", width: 1200, height: 628, templateId: "..." }

// /generate-preview - Returns raw PNG (for testing/previews)
const previewResponse = await fetch('https://api.socialrenders.com/generate-preview', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_your_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({ templateId: 'twitter-post', fields: { ... } })
});
const imageBuffer = await previewResponse.arrayBuffer(); // PNG binary
```

## Notes

- Images: 1200px wide, height auto-adapts (400-1200px)
- All fields optional with defaults
- Use `\n` for line breaks in text
- `/generate` uploads to R2 and returns JSON with URL
- `/generate-preview` returns raw PNG
- PNG format only
- **Image Retention**: Generated images are hosted for 48 hours. Download and save them if you need them longer.