Skip to content

API_GUIDE.md

Latest commit

 

History

History
204 lines (158 loc) · 5.29 KB

API_GUIDE.md

File metadata and controls

204 lines (158 loc) · 5.29 KB

Napkin AI API Guide

CHANGE TO GUIDE

Getting Started

Prerequisites

Installation

# Clone repository
git clone https://github.com/moshehbenavraham/Napkin-AI-API.git
cd Napkin-AI-API

# Install dependencies
poetry install

# Configure API token
cp .env.example .env
echo "NAPKIN_API_TOKEN=your_token_here" >> .env

Usage

Web Interface (Streamlit)

poetry run streamlit run streamlit_app.py
# Access at http://localhost:8501

Features:

  • Interactive visual generation
  • 16 built-in styles + custom styles
  • 38 language support
  • Real-time preview and download

Command Line Interface

# Basic generation
poetry run napkin generate "Your content"

# With options
poetry run napkin generate "Data Flow" \
  --style sketch-notes \
  --format png \
  --language es-ES \
  --variations 2

# List available styles
poetry run napkin styles --list

# Check configuration
poetry run napkin config --check

API Reference

Base Configuration

  • Base URL: https://api.napkin.ai
  • Version: v1
  • Authentication: Bearer token required
  • Rate Limit: 60 requests/minute

Core Endpoints

1. Create Visual Request

POST /v1/visual

import httpx
import asyncio

data = {
    "format": "svg",  # or "png"
    "content": "Your text content",
    "style_id": "CDQPRVVJCSTPRBBCD5Q6AWR",  # Optional
    "language": "en-US",  # BCP 47 tag
    "number_of_visuals": 1,  # 1-4
    "transparent_background": False,
    "width": 1200,  # PNG only
    "context_before": "Introduction to",
    "context_after": "for beginners"
}

async def create_visual():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://api.napkin.ai/v1/visual",
            headers={"Authorization": "Bearer YOUR_TOKEN"},
            json=data
        )
        return response.json()

result = asyncio.run(create_visual())
print(f"Request ID: {result['id']}")

2. Check Status

GET /v1/visual/{request_id}/status

async def check_status(request_id):
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.napkin.ai/v1/visual/{request_id}/status",
            headers={"Authorization": "Bearer YOUR_TOKEN"}
        )
        return response.json()

# Poll until complete
status = "pending"
while status == "pending":
    result = asyncio.run(check_status(request_id))
    status = result["status"]
    if status == "pending":
        await asyncio.sleep(3)

3. Download File

GET /v1/visual/{request_id}/file/{file_id}

async def download_file(request_id, file_id, output_path):
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://api.napkin.ai/v1/visual/{request_id}/file/{file_id}",
            headers={"Authorization": "Bearer YOUR_TOKEN"}
        )
        with open(output_path, "wb") as f:
            f.write(response.content)

Available Styles

Colorful Styles

Style ID Description
Vibrant Strokes CDQPRVVJCSTPRBBCD5Q6AWR Bold, vivid lines
Glowful Breeze CDQPRVVJCSTPRBBKDXK78 Cheerful colors
Bold Canvas CDQPRVVJCSTPRBB6DHGQ8 Lively shapes
Radiant Blocks CDQPRVVJCSTPRBB6D5P6RSB4 Solid colors
Pragmatic Shades CDQPRVVJCSTPRBB7E9GP8TB5DST0 Blended hues

Hand-drawn Styles

Style ID Description
Artistic Flair D1GPWS1DCDQPRVVJCSTPR Creative hand-drawn
Sketch Notes D1GPWS1DDHMPWSBK Free-flowing sketches

Formal Styles

Style ID Description
Elegant Outline CSQQ4VB1DGPP4V31CDNJTVKFBXK6JV3C Professional clarity
Subtle Accent CSQQ4VB1DGPPRTB7D1T0 Light professional
Corporate Clean CSQQ4VB1DGPPTVVEDXHPGWKFDNJJTSKCC5T0 Business diagrams

Casual & Monochrome

Style ID Description
Carefree Mist CDGQ6XB1DGPQ6VV6EG Playful tasks
Lively Layers CDGQ6XB1DGPPCTBCDHJP8 Soft colors
Minimal Contrast DNQPWVV3D1S6YVB55NK6RRBM Clean monochrome
Silver Beam CXS62Y9DCSQP6XBK Grayscale focus

Error Handling

Status Code Description Action
201 Request created Poll for status
400 Invalid parameters Check request data
401 Invalid token Verify API token
429 Rate limit exceeded Wait and retry
410 Request expired Create new request

Best Practices

  1. Implement exponential backoff when polling
  2. Cache generated visuals to avoid redundant API calls
  3. Download files immediately (URLs expire after 30 minutes)
  4. Use SVG format for scalability, PNG for specific dimensions
  5. Add context for better visual generation
  6. Specify language for non-English content

Security

  • Never expose API tokens in client-side code
  • Use environment variables for sensitive data
  • Implement server-side proxy for web applications
  • Rotate tokens regularly

Support