API Quickstart

API Quickstart

Get up and running with the ImageBot API in just a few minutes.

Prerequisites

• Active ImageBot account
• API key (create in Settings → API Keys)

Step 1: Create an API Key

1. Navigate to Settings → API Keys
2. Click Create New Key
3. Configure permissions:
   • generate: Create images
   • read: View images and collections
   • manage: Full access (delete, update)
4. Copy your API key (shown once)

Important: Store your API key securely. It won’t be shown again.

Step 2: Make Your First Request

Authentication

All API requests require your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate an Image

curl -X POST https://imagebot-worker.andrea-b56.workers.dev/api/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain landscape at sunset",
    "model": "@cf/black-forest-labs/flux-1-schnell"
  }'

Response:

{
  "id": "img_abc123",
  "prompt": "A serene mountain landscape at sunset",
  "model": "@cf/black-forest-labs/flux-1-schnell",
  "r2_key": "generated/img_abc123.png",
  "r2_url": "https://imagebot-images.r2.dev/generated/img_abc123.png",
  "created_at": "2024-01-15T10:30:00Z"
}

Step 3: Retrieve Generated Images

curl -X GET https://imagebot-worker.andrea-b56.workers.dev/api/images \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "images": [
    {
      "id": "img_abc123",
      "prompt": "A serene mountain landscape at sunset",
      "model": "@cf/black-forest-labs/flux-1-schnell",
      "r2_url": "https://imagebot-images.r2.dev/generated/img_abc123.png",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Common Use Cases

Batch Generation

Process multiple prompts:

const prompts = [
  "Mountain landscape at sunset",
  "Ocean waves at golden hour",
  "Forest path in autumn"
];

for (const prompt of prompts) {
  const response = await fetch('https://imagebot-worker.andrea-b56.workers.dev/api/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt, model: '@cf/black-forest-labs/flux-1-schnell' })
  });

  const image = await response.json();
  console.log(`Generated: ${image.id}`);
}

Create a Collection

Organize images into projects:

curl -X POST https://imagebot-worker.andrea-b56.workers.dev/api/collections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Campaign 2024",
    "description": "Social media assets for Q1 campaign"
  }'

Add Image to Collection

curl -X POST https://imagebot-worker.andrea-b56.workers.dev/api/collections/coll_xyz789/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_id": "img_abc123"
  }'

Rate Limits

• Standard Plan: 100 requests/minute
• Pro Plan: 500 requests/minute
• Enterprise Plan: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1673784000

Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Error Response Format:

{
  "error": "Invalid prompt parameter",
  "code": "INVALID_PARAMETER",
  "details": {
    "field": "prompt",
    "message": "Prompt must be at least 3 characters"
  }
}

SDK Examples

JavaScript/Node.js

class ImageBotClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://imagebot-worker.andrea-b56.workers.dev';
  }

  async generate(prompt, model = '@cf/black-forest-labs/flux-1-schnell') {
    const response = await fetch(`${this.baseUrl}/api/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ prompt, model })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    return await response.json();
  }

  async getImages(limit = 20, offset = 0) {
    const response = await fetch(
      `${this.baseUrl}/api/images?limit=${limit}&offset=${offset}`,
      {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      }
    );

    return await response.json();
  }
}

// Usage
const client = new ImageBotClient('your-api-key');
const image = await client.generate('A beautiful sunset over mountains');
console.log(image);

Python

import requests

class ImageBotClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://imagebot-worker.andrea-b56.workers.dev'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def generate(self, prompt, model='@cf/black-forest-labs/flux-1-schnell'):
        response = requests.post(
            f'{self.base_url}/api/generate',
            headers=self.headers,
            json={'prompt': prompt, 'model': model}
        )
        response.raise_for_status()
        return response.json()

    def get_images(self, limit=20, offset=0):
        response = requests.get(
            f'{self.base_url}/api/images',
            headers=self.headers,
            params={'limit': limit, 'offset': offset}
        )
        response.raise_for_status()
        return response.json()

# Usage
client = ImageBotClient('your-api-key')
image = client.generate('A beautiful sunset over mountains')
print(image)

Webhooks

Get notified when operations complete:

// Configure webhook URL when creating batch job
const response = await fetch('https://imagebot-worker.andrea-b56.workers.dev/api/batch/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Marketing Batch',
    prompts: ['prompt1', 'prompt2', 'prompt3'],
    model: '@cf/black-forest-labs/flux-1-schnell',
    webhook_url: 'https://your-server.com/webhook'
  })
});

// Your webhook will receive:
{
  "event": "batch.completed",
  "batch_id": "batch_xyz",
  "status": "completed",
  "total_prompts": 3,
  "completed_count": 3,
  "failed_count": 0,
  "images": [
    { "id": "img_1", "prompt": "prompt1", "r2_url": "..." },
    { "id": "img_2", "prompt": "prompt2", "r2_url": "..." },
    { "id": "img_3", "prompt": "prompt3", "r2_url": "..." }
  ]
}

Next Steps

• Complete API Reference
• Authentication Guide
• Batch Processing
• Team Collaboration

Support

• API Documentation: /docs/api/reference
• GitHub Issues: github.com/your-org/imagebot/issues
• Email: support@imagebot.com