Quick Start

Quick Start

Get up and running with Splinterpic in just a few minutes. This guide will walk you through making your first API call and generating your first AI image.

Prerequisites

Before you begin, make sure you have:

• A Splinterpic account (sign up at splinterpic.app)
• Your Worker API URL (find in Settings)
• Basic familiarity with REST APIs

Step 1: Understand the API Endpoint

Splinterpic uses a simple REST API. Your Worker URL will look like:

https://splinterpic-worker.your-name.workers.dev

All API requests are sent to this base URL + the endpoint path.

Step 2: Make Your First Request

Let’s generate an image! No authentication required for the basic setup (though you should enable IP whitelisting for production).

cURL:

curl -X POST https://splinterpic-worker.your-name.workers.dev/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic city with flying cars at sunset, cyberpunk style",
    "model": "@cf/black-forest-labs/flux-1-schnell"
  }'

JavaScript:

const API_URL = 'https://splinterpic-worker.your-name.workers.dev';

async function generateImage() {
  const response = await fetch(`${API_URL}/api/generate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'A futuristic city with flying cars at sunset, cyberpunk style',
      model: '@cf/black-forest-labs/flux-1-schnell'
    })
  });

  const data = await response.json();
  console.log('Image generated:', data);
  return data;
}

generateImage();

Python:

import requests
import json

API_URL = 'https://splinterpic-worker.your-name.workers.dev'

def generate_image():
    response = requests.post(
        f'{API_URL}/api/generate',
        headers={'Content-Type': 'application/json'},
        json={
            'prompt': 'A futuristic city with flying cars at sunset, cyberpunk style',
            'model': '@cf/black-forest-labs/flux-1-schnell'
        }
    )

    data = response.json()
    print('Image generated:', data)
    return data

generate_image()

Response

You’ll receive a JSON response like this:

{
  "id": "img_1a2b3c4d5e6f",
  "prompt": "A futuristic city with flying cars at sunset, cyberpunk style",
  "model": "@cf/black-forest-labs/flux-1-schnell",
  "r2_key": "generated/img_1a2b3c4d5e6f.png",
  "r2_url": "https://your-bucket.r2.dev/generated/img_1a2b3c4d5e6f.png",
  "created_at": "2024-01-15T10:30:00.000Z",
  "user_id": "default_user",
  "cost": 0.01
}

Step 3: Retrieve Generated Images

List all your generated images:

cURL:

curl https://splinterpic-worker.your-name.workers.dev/api/images

JavaScript:

async function getImages() {
  const response = await fetch(`${API_URL}/api/images`);
  const images = await response.json();
  console.log('Your images:', images);
  return images;
}

getImages();

Python:

def get_images():
    response = requests.get(f'{API_URL}/api/images')
    images = response.json()
    print('Your images:', images)
    return images

get_images()

Response

{
  "images": [
    {
      "id": "img_1a2b3c4d5e6f",
      "prompt": "A futuristic city...",
      "model": "@cf/black-forest-labs/flux-1-schnell",
      "r2_url": "https://your-bucket.r2.dev/generated/img_1a2b3c4d5e6f.png",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}

Step 4: Explore Available Models

See which AI models are available:

cURL:

curl https://splinterpic-worker.your-name.workers.dev/api/models

JavaScript:

async function getModels() {
  const response = await fetch(`${API_URL}/api/models`);
  const models = await response.json();
  console.log('Available models:', models);
  return models;
}

getModels();

Python:

def get_models():
    response = requests.get(f'{API_URL}/api/models')
    models = response.json()
    print('Available models:', models)
    return models

get_models()

Response

{
  "models": [
    {
      "id": "@cf/black-forest-labs/flux-1-schnell",
      "name": "Flux 1 Schnell",
      "description": "Fast, high-quality image generation",
      "cost_per_image": 0.01,
      "is_recommended": true
    },
    {
      "id": "@cf/stabilityai/stable-diffusion-xl-base-1.0",
      "name": "Stable Diffusion XL",
      "description": "Versatile, detailed image generation",
      "cost_per_image": 0.02,
      "is_recommended": false
    }
  ]
}

Step 5: Organize with Collections

Create a collection to organize your images:

cURL:

curl -X POST https://splinterpic-worker.your-name.workers.dev/api/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Campaign 2024",
    "description": "Images for Q1 social media campaign"
  }'

JavaScript:

async function createCollection() {
  const response = await fetch(`${API_URL}/api/collections`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: 'Marketing Campaign 2024',
      description: 'Images for Q1 social media campaign'
    })
  });

  const collection = await response.json();
  console.log('Collection created:', collection);
  return collection;
}

createCollection();

Python:

def create_collection():
    response = requests.post(
        f'{API_URL}/api/collections',
        json={
            'name': 'Marketing Campaign 2024',
            'description': 'Images for Q1 social media campaign'
        }
    )

    collection = response.json()
    print('Collection created:', collection)
    return collection

create_collection()

Common Patterns

Batch Generation

Generate multiple images from a list of prompts:

const prompts = [
  'Mountain landscape at sunrise',
  'Ocean waves during golden hour',
  'Forest path in autumn',
  'Desert dunes at sunset'
];

async function batchGenerate(prompts) {
  const results = [];

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

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

  return results;
}

batchGenerate(prompts);

Error Handling

Always handle errors gracefully:

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

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

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Generation failed:', error);
    throw error;
  }
}

Next Steps

Now that you’ve generated your first images, explore these topics:

• Authentication - Secure your API with IP whitelisting Learn more →
• API Reference - Explore all available endpoints View docs →
• SDKs - Use official SDKs for easier integration Browse SDKs →
• Deployment - Deploy to production with best practices Deploy →

Troubleshooting

CORS Errors

If you’re seeing CORS errors, make sure your Worker is configured to allow cross-origin requests. The Worker includes CORS headers by default.

IP Whitelist Blocking

If requests are being blocked, check your IP whitelist configuration in wrangler.toml:

[vars]
ALLOWED_IPS = "your.ip.address,another.ip.address"

Images Not Displaying

If images aren’t displaying, verify:

1. R2 bucket is properly configured
2. R2 URLs are publicly accessible (configure custom domain)
3. Image generation completed successfully

Support

Questions? We’re here to help:

• Documentation: Full API Reference
• GitHub: Open an issue
• Email: support@splinterpic.com