Auto Toon Docs

API Documentation

Everything you need to integrate Auto Toon into your applications.

Quick Start

1. Get your API key

2. Make your first request

Use your API key to convert JSON to TOON format:

curl -X POST https://www.auto-toon.com/api/convert/json-to-toon \
  -H "Content-Type: application/json" \
  -H "x-api-key: toon_xxxx_your_api_key" \
  -d '{"payload": {"name": "John", "age": 30}}'

3. Get your response

The API returns the TOON-encoded data along with usage statistics:

{
  "toon": "~name|John~age|30",
  "usage": {
    "inputTokens": 8,
    "outputTokens": 5,
    "tokensSaved": 3
  }
}

Authentication

All API requests require authentication using an API key. Include your key in the x-api-key header:

curl -H "x-api-key: toon_xxxx_your_api_key" \
  https://www.auto-toon.com/api/convert/json-to-toon

Keep your API key secret! Never expose it in client-side code or public repositories.

API Endpoints

POST/api/convert/json-to-toon

Convert JSON data to TOON format. Reduces token count for LLM applications.

Request Body

{
  "payload": <any valid JSON>
}

Response

{
  "toon": "<encoded TOON string>",
  "usage": {
    "inputTokens": <number>,
    "outputTokens": <number>,
    "tokensSaved": <number>
  }
}

Example

curl -X POST https://www.auto-toon.com/api/convert/json-to-toon \
  -H "Content-Type: application/json" \
  -H "x-api-key: toon_xxxx_your_api_key" \
  -d '{
    "payload": {
      "users": [
        {"id": 1, "name": "Alice", "email": "alice@example.com"},
        {"id": 2, "name": "Bob", "email": "bob@example.com"}
      ]
    }
  }'

POST/api/convert/toon-to-json

Convert TOON-encoded data back to JSON format.

Request Body

{
  "toon": "<TOON encoded string>"
}

Response

{
  "json": <decoded JSON data>
}

POST/api/enhance-product

Generate AI-enhanced product images with customizable styles. Supports hero image generation, vignettes, decorative elements, and promotional posters.

Credit Cost: 3 credits per image (Gemini Pro), 1 credit per image (Seedream). Hero image + optional second image = 6 credits total by default with Gemini Pro.

Request Parameters

Field	Type	Required	Description
`imageUrl`	string	✅	URL of the product image (max 2000 chars)
`productName`	string	✅	Name of the product (1-200 chars)
`model`	string	❌	`gemini` (2cr, default), `gemini-flash` (1cr), or `seedream` (1cr)
`type`	string	❌	`vignette` (default), `elements`, `poster`, or `3x3`
`skipSecondImage`	boolean	❌	If true, only generate hero image (saves 1 credit)
`skipHeroImage`	boolean	❌	If true, only generate second image (saves 1 credit)
`promptCustomizations`	object	❌	Customize hero image: `background`, `lighting`, `composition`
`elementsConfig`	object	❌	For elements type: `keyElements[]`, `enhancers[]`
`posterConfig`	object	❌	For poster type: `headline`, `primaryColor`, `tagline`, etc.
`seedreamConfig`	object	❌	For seedream model: `aspect_ratio` (e.g., "2:3", "16:9")

Example 1: Simple Request (Default)

Generates hero + vignette images (6 credits)

{
  "imageUrl": "https://images.unsplash.com/photo-1620916566398-39f1143ab7be?w=800",
  "productName": "Luxury Skincare Serum"
}

Response:

{
  "text": "**Luxury Skincare Serum** - $45\n\nPremium anti-aging formula...\n\n✓ Reduces fine lines\n✓ Deep hydration\n✓ Natural ingredients",
  "heroImageUrl": "https://supabase.co/.../hero_1234.png",
  "vignetteImageUrl": "https://supabase.co/.../vignette_1234.png",
  "labels": ["Reduces fine lines", "Deep hydration", "Natural ingredients", "Anti-aging", "Vitamin E"],
  "creditsRemaining": 8,
  "success": true
}

Example 2: Hero Only (Fast & Cheap)

Only hero image with gemini-flash model (1 credit)

{
  "imageUrl": "https://images.unsplash.com/photo-1620916566398-39f1143ab7be?w=800",
  "productName": "Premium Face Cream",
  "model": "gemini-flash",
  "skipSecondImage": true
}

Response:

{
  "text": "**Premium Face Cream** - $38\n\nLuxurious moisturizer...\n\n✓ 24h hydration\n✓ Smooth texture\n✓ Fast absorption",
  "heroImageUrl": "https://supabase.co/.../hero_5678.png",
  "vignetteImageUrl": null,
  "labels": ["24h hydration", "Smooth texture", "Fast absorption", "Lightweight", "Non-greasy"],
  "creditsRemaining": 9,
  "success": true
}

Example 3: Elements Style

Product with decorative elements and custom effects (6 credits)

{
  "imageUrl": "https://images.unsplash.com/photo-1620916566398-39f1143ab7be?w=800",
  "productName": "Energy Drink",
  "type": "elements",
  "elementsConfig": {
    "keyElements": [
      "Product clearly visible",
      "Dynamic splash effects",
      "Fresh ingredients"
    ],
    "enhancers": [
      "Vibrant colors",
      "Motion blur",
      "Sparkle effects"
    ]
  }
}

Response:

{
  "text": "**Energy Drink** - $3.99\n\nBoost your energy naturally...\n\n✓ Natural caffeine\n✓ Zero sugar\n✓ Vitamin B complex",
  "heroImageUrl": "https://supabase.co/.../hero_9012.png",
  "vignetteImageUrl": "https://supabase.co/.../elements_9012.png",
  "labels": ["Natural caffeine", "Zero sugar", "Vitamin B complex", "Refreshing", "Energy boost"],
  "creditsRemaining": 6,
  "success": true
}

Example 4: Poster Style

Marketing poster with custom branding (6 credits)

{
  "imageUrl": "https://images.unsplash.com/photo-1620916566398-39f1143ab7be?w=800",
  "productName": "Luxury Serum",
  "type": "poster",
  "posterConfig": {
    "headline": "PREMIUM SERUM",
    "tagline": "Transform your skin with nature",
    "primaryColor": "rose gold",
    "colorScheme": "monochromatic",
    "aspectRatio": "4:5"
  }
}

Response:

{
  "text": "**Luxury Serum** - $89\n\nPremium botanical serum...\n\n✓ Organic ingredients\n✓ Clinically tested\n✓ Visible results",
  "heroImageUrl": "https://supabase.co/.../hero_3456.png",
  "vignetteImageUrl": "https://supabase.co/.../poster_3456.png",
  "labels": ["Organic ingredients", "Clinically tested", "Visible results", "Luxury formula", "Anti-aging"],
  "creditsRemaining": 4,
  "success": true
}

Example 5: Full Customization

Hero image with custom background, lighting, and composition (6 credits)

{
  "imageUrl": "https://images.unsplash.com/photo-1620916566398-39f1143ab7be?w=800",
  "productName": "Anti-Aging Cream",
  "model": "gemini",
  "promptCustomizations": {
    "background": "vast empty gradient canvas in champagne gold tones",
    "lighting": "soft, subtle studio lighting with controlled highlights",
    "composition": "single product positioned in the center of the frame with balanced negative space"
  },
  "type": "vignette"
}

Response:

{
  "text": "**Anti-Aging Cream** - $65\n\nAdvanced age-defying formula...\n\n✓ Reduces wrinkles\n✓ Firms skin\n✓ Brightens complexion",
  "heroImageUrl": "https://supabase.co/.../hero_7890.png",
  "vignetteImageUrl": "https://supabase.co/.../vignette_7890.png",
  "labels": ["Reduces wrinkles", "Firms skin", "Brightens complexion", "Collagen boost", "Retinol"],
  "creditsRemaining": 2,
  "success": true
}

Error Response Example

{
  "text": "**Premium Skincare Serum** - $45\n\nLuxury anti-aging serum...\n\n✓ Reduces fine lines\n✓ Hydrates deeply\n✓ Natural ingredients",
  "heroImageUrl": "https://supabase.co/.../generated/user-id/timestamp_hero.png",
  "vignetteImageUrl": "https://supabase.co/.../generated/user-id/timestamp_vignette.png",
  "labels": ["Reduces fine lines", "Hydrates deeply", "Natural ingredients", "Anti-aging", "Vitamin E"],
  "creditsRemaining": 8,
  "success": true
}

Error Response

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "balance": 0,
  "required": 2,
  "needsTopUp": true
}

Error Codes

Code	Description
`400`	Bad Request - Invalid JSON or TOON format
`401`	Unauthorized - Missing or invalid API key
`429`	Rate Limit Exceeded - Too many requests
`500`	Internal Server Error - Something went wrong

Rate Limits

API requests are rate limited to ensure fair usage:

Basic Plan: 100 requests per minute

Rate limit headers are included in all responses: X-RateLimit-Remaining

Ready to get started?

Create your API key and start converting in minutes.

API Documentation

Quick Start

1. Get your API key

2. Make your first request

3. Get your response

Authentication

API Endpoints

Request Body

Response

Example

Request Body

Response

Request Parameters

Example 1: Simple Request (Default)

Example 2: Hero Only (Fast & Cheap)

Example 3: Elements Style

Example 4: Poster Style

Example 5: Full Customization

Error Response Example

Error Response

Error Codes

Rate Limits

Ready to get started?

Dialog Title

Dialog Title

Dialog Title

Dialog Title