Quick Start

Get up and running with Tonta in less than 5 minutes. This guide will walk you through creating your first uploader and integrating it into your application.

1. Create an Account

Sign up for a free account at dash.tonta.io. You'll get instant access to create uploaders and manage your files.

2. Create Your First Uploader

From your dashboard, click "Create Uploader" and configure your settings:

JSON

{
  "name": "My First Uploader",
  "allowed_types": ["image/jpeg", "image/png", "image/webp"],
  "max_file_size": 10485760,  // 10MB
  "processing": {
    "resize": {
      "width": 1920,
      "height": 1080,
      "mode": "fit"
    },
    "optimize": true,
    "convert_to_webp": true
  }
}

3. Add to Your Website

Add the uploader script to your HTML page:

HTML

<!-- Target element -->
<div class="my-uploader"></div>

<!-- Tonta script -->
<script src="https://tonta.io/uploader/uploader.js"
        data-backend="https://api.tonta.io/upload"
        data-target=".my-uploader"
        data-api-key="YOUR_API_KEY"
        data-callback="handleUpload"></script>

<!-- Handle uploads -->
<script>
window.handleUpload = {
    onUploadComplete(file, result) {
        console.log('Uploaded:', result.files[0].link);
        // Use the uploaded image URL
        document.getElementById('preview').src = result.files[0].link;
    }
};
</script>

Authentication

Tonta uses API keys to authenticate requests. You can find your API keys in the dashboard under Settings → API Keys.

Using API Keys

Include your API key in the X-API-Key header for all API requests:

BASH

curl -X POST https://api.tonta.io/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@image.jpg"

Domain Restrictions

For added security, you can restrict API keys to specific domains. This prevents unauthorized use if your key is exposed in client-side code.

Security Best Practices

Use domain restrictions for client-side keys
Keep server-side keys secret
Rotate keys regularly
Use environment variables for key storage

Upload API

The Upload API is the core of Tonta. Use it to upload files programmatically from any application or platform.

Endpoint

Method	Endpoint	Description
POST	`/upload`	Upload one or more files

Request Parameters

Parameter	Type	Required	Description
`file`	File	Yes	The file to upload (can be multiple)
`uploader_id`	String	No	Specific uploader configuration to use
`metadata`	JSON	No	Custom metadata to attach to the file

XMP Metadata Parameters (New!)

Note: XMP metadata embedding must be enabled in your uploader settings. When enabled, metadata is permanently embedded directly into the image file.

Parameter	Type	Description
`xmp_keywords`	String	Comma-separated keywords/tags for the image
`xmp_title`	String	Title of the image
`xmp_description`	String	Detailed description of the image
`xmp_creator`	String	Creator/photographer name
`xmp_copyright`	String	Copyright information
`xmp_custom_*`	String	Custom metadata fields (replace * with your field name)

Example Request

JAVASCRIPT

const formData = new FormData();
formData.append('file', fileInput.files[0]);

// Optional: Add custom metadata (stored in database)
formData.append('metadata', JSON.stringify({
    title: 'Product Image',
    category: 'electronics'
}));

// Optional: Add XMP metadata (embedded in image file)
formData.append('xmp_keywords', 'product, electronics, smartphone');
formData.append('xmp_title', 'Latest Smartphone Model');
formData.append('xmp_description', 'High-resolution product photo of our latest smartphone');
formData.append('xmp_creator', 'John Doe Photography');
formData.append('xmp_copyright', '© 2025 Your Company. All rights reserved.');

const response = await fetch('https://api.tonta.io/upload', {
    method: 'POST',
    headers: {
        'X-API-Key': 'YOUR_API_KEY'
    },
    body: formData
});

const result = await response.json();
console.log('Uploaded:', result.files[0].link);

Response Format

JSON

{
  "success": true,
  "files": [
    {
      "id": "abc123def456",
      "smallid": "Ax7Bz9",
      "link": "https://cdn.tonta.io/abc123def456.jpg",
      "thumbnail": "https://cdn.tonta.io/abc123def456_thumb.jpg",
      "size": 245632,
      "type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "metadata": {
        "title": "Product Image",
        "category": "electronics"
      },
      "created_at": "2025-01-02T10:30:00Z"
    }
  ]
}

File Management

Manage your uploaded files programmatically with our file management endpoints.

List Files

Method	Endpoint	Description
GET	`/files`	List all files with pagination

BASH

curl -X GET "https://api.tonta.io/files?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Get File Details

Method	Endpoint	Description
GET	`/files/{id}`	Get details for a specific file

Delete File

Method	Endpoint	Description
DELETE	`/files/{id}`	Delete a file permanently

Important

Deleting a file is permanent and cannot be undone. The file will be removed from all CDN locations within 60 seconds.

Webhooks

Receive real-time notifications when events occur in your Tonta account. Perfect for building automated workflows.

Configuring Webhooks

Add webhook endpoints in your dashboard under Settings → Webhooks. You can configure different endpoints for different events.

Available Events

Event	Description
`upload.complete`	Fired when a file upload is successfully completed
`upload.failed`	Fired when a file upload fails
`file.deleted`	Fired when a file is deleted
`processing.complete`	Fired when image processing is complete

Webhook Payload

JSON

{
  "event": "upload.complete",
  "timestamp": "2025-01-02T10:30:00Z",
  "data": {
    "file": {
      "id": "abc123def456",
      "link": "https://cdn.tonta.io/abc123def456.jpg",
      "size": 245632,
      "type": "image/jpeg"
    },
    "uploader": {
      "id": "uploader_xyz789",
      "name": "Product Images"
    }
  }
}

Verifying Webhooks

All webhook requests include a signature in the X-Tonta-Signature header. Verify this signature to ensure the request is from Tonta:

JAVASCRIPT

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
    const hash = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    
    return hash === signature;
}

Error Handling

Tonta uses standard HTTP response codes to indicate success or failure. All error responses include a detailed message to help you debug.

Error Response Format

JSON

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds the maximum allowed size of 10MB",
    "details": {
      "file_size": 15728640,
      "max_size": 10485760
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	The provided API key is invalid or missing
`FILE_TOO_LARGE`	413	File exceeds the maximum allowed size
`INVALID_FILE_TYPE`	415	File type is not allowed by the uploader
`QUOTA_EXCEEDED`	429	Upload quota has been exceeded
`SERVER_ERROR`	500	An unexpected error occurred

Image Processing

Tonta automatically processes images based on your uploader configuration. You can resize, optimize, add watermarks, and more.

Processing Options

JSON

{
  "processing": {
    "resize": {
      "width": 1920,
      "height": 1080,
      "mode": "fit",  // "fit", "fill", "crop", "stretch"
      "gravity": "center"  // "center", "north", "south", etc.
    },
    "optimize": true,
    "quality": 85,  // 1-100
    "convert_to_webp": true,
    "watermark": {
      "image": "https://example.com/watermark.png",
      "position": "bottom-right",
      "opacity": 0.5,
      "scale": 0.2
    },
    "variants": [
      {
        "name": "thumbnail",
        "width": 200,
        "height": 200,
        "mode": "crop"
      },
      {
        "name": "mobile",
        "width": 768,
        "quality": 90
      }
    ]
  }
}

On-Demand Processing

You can also process images on-demand using URL parameters:

HTML

<!-- Resize to 400x300 -->
<img src="https://cdn.tonta.io/image.jpg?w=400&h=300">

<!-- Convert to WebP with 80% quality -->
<img src="https://cdn.tonta.io/image.jpg?format=webp&q=80">

<!-- Crop to square -->
<img src="https://cdn.tonta.io/image.jpg?w=500&h=500&mode=crop">

XMP Metadata Embedding (New Feature!)

XMP (Extensible Metadata Platform) allows you to embed searchable metadata directly into image files. This metadata travels with the image file and can be read by photo management software, search engines, and digital asset management systems.

Enabling XMP Metadata

Navigate to your uploader settings in the dashboard
Toggle "Enable XMP Metadata Embedding" to ON
Save your uploader configuration

Benefits of XMP Metadata

SEO Enhancement: Search engines can read embedded metadata for better image indexing
Copyright Protection: Embed copyright and creator information directly in the file
Asset Management: Keywords and descriptions help organize large image libraries
Permanence: Metadata stays with the file even when downloaded or transferred
Industry Standard: Compatible with Adobe Creative Suite and professional DAM systems

Supported Metadata Fields

Field	XMP Property	Use Case
`xmp_keywords`	dc:subject	Searchable tags for categorization and SEO
`xmp_title`	dc:title	Image title for display and search
`xmp_description`	dc:description	Detailed description for context and accessibility
`xmp_creator`	dc:creator	Photographer or creator attribution
`xmp_copyright`	dc:rights	Copyright notice and usage rights

Example: E-commerce Product Images

JAVASCRIPT

// Upload product image with rich metadata
const formData = new FormData();
formData.append('file', productImage);

// Embed product information in the image
formData.append('xmp_keywords', 'laptop, gaming, RGB, 16GB RAM, RTX 4070');
formData.append('xmp_title', 'Gaming Laptop Pro X1');
formData.append('xmp_description', 'High-performance gaming laptop with RTX 4070 graphics');
formData.append('xmp_creator', 'Product Photography Team');
formData.append('xmp_copyright', '© 2025 YourStore.com');

// Custom fields for internal tracking
formData.append('xmp_custom_sku', 'LAPTOP-GX1-2025');
formData.append('xmp_custom_price', '$1,499');

await fetch('https://uploader.tonta.io/', {
    method: 'POST',
    headers: { 'X-API-Key': 'your_api_key' },
    body: formData
});

Verifying Embedded Metadata

You can verify that metadata has been successfully embedded using:

Adobe Photoshop: File → File Info
Adobe Bridge: View metadata panel
Command Line: exiftool image.jpg
Online Tools: Various EXIF/XMP viewers
Windows: Right-click → Properties → Details
macOS: Preview → Tools → Show Inspector

Updating XMP Metadata on Existing Images

You can add or update XMP metadata on images that have already been uploaded using our dedicated API endpoint. This is useful when you need to add metadata after the fact, or update existing metadata.

API Endpoint

ENDPOINT

POST https://uploader.tonta.io/xmp-update.php

Request Headers

Header	Value	Description
`X-API-Key`	Your API key	Must be the same API key used for uploading
`Content-Type`	application/json	Request body format

Request Body

Field	Type	Required	Description
`file_id`	String	Yes	The base ID from the upload response (without file extension)
`xmp_keywords`	String	No*	Comma-separated keywords for search
`xmp_title`	String	No*	Title of the image
`xmp_description`	String	No*	Detailed description
`xmp_creator`	String	No*	Creator/photographer name
`xmp_copyright`	String	No*	Copyright notice

* At least one metadata field must be provided

Example Request

CURL

curl -X POST https://uploader.tonta.io/xmp-update.php \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "aBcDeFgH123",
    "xmp_keywords": "product, photography, studio",
    "xmp_title": "Product Shot",
    "xmp_description": "Professional product photography",
    "xmp_creator": "Studio Name",
    "xmp_copyright": "© 2025 Company Name"
  }'

Example Response

JSON

{
  "success": true,
  "message": "XMP metadata successfully added to image",
  "file_id": "aBcDeFgH123.jpg",
  "url": "https://files.lilassistance.com/aBcDeFgH123.jpg",
  "metadata": {
    "keywords": "product, photography, studio",
    "title": "Product Shot",
    "description": "Professional product photography",
    "creator": "Studio Name",
    "copyright": "© 2025 Company Name"
  }
}

Important Notes

⚡ Performance: XMP embedding adds minimal processing time (typically <100ms per image)

📏 File Size: Metadata typically adds 3-4KB to file size due to the XMP packet

🖼️ Format Support: Works with JPEG and PNG formats (not WebP)

🔄 Re-upload: The file is re-uploaded to storage after metadata is embedded

💾 Keep Original: The uploader must have "Keep Original" enabled for processed images

⏱️ CDN Caching: Due to CDN caching, updated files may take a few minutes to be visible

🔒 Privacy: Be mindful of sensitive information in metadata as it travels with the file

Documentation

Quick Start

1. Create an Account

2. Create Your First Uploader

3. Add to Your Website

Authentication

Using API Keys

Domain Restrictions

Security Best Practices

Upload API

Endpoint

Request Parameters

XMP Metadata Parameters (New!)

Example Request

Response Format

File Management

List Files

Get File Details

Delete File

Important

Webhooks

Configuring Webhooks

Available Events

Webhook Payload

Verifying Webhooks

Error Handling

Error Response Format

Common Error Codes

Image Processing

Processing Options

On-Demand Processing

XMP Metadata Embedding (New Feature!)

Enabling XMP Metadata

Benefits of XMP Metadata

Supported Metadata Fields

Example: E-commerce Product Images

Verifying Embedded Metadata

Updating XMP Metadata on Existing Images

API Endpoint

Request Headers

Request Body

Example Request

Example Response

Important Notes