Docs

Quick Start

Sign in at dash.tonta.io, create an uploader, and copy the generated API key. Each uploader controls allowed domains, resizing rules, watermarking, and whether original files are retained.

Embed the Uploader Widget

HTML
<div class="my-uploader"></div>

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

<script>
window.handleUpload = {
  onUploadComplete(file, result) {
    console.log('Uploaded file ID:', result.id);
    document.querySelector('#preview').src = result.link;
  }
};
</script>
            

Authentication

Every API request is authenticated with the uploader's API key. The key is tied to the uploader configuration and inherits its domain restrictions.

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

Domain restrictions

Add every origin that will embed the uploader (e.g. studio.example.com).
Origins that are not listed receive 403 Domain not allowed.
Rotate keys in the dashboard if one is ever exposed.

Upload API

Method	Endpoint	Description
POST	`https://tonta.io/uploader/upload.php`	Upload one or more files via `multipart/form-data`

Form Fields

Field	Required	Description
`file`	Yes	The file input; repeat the field to send multiple files.
`metadata`	No	JSON blob stored alongside the file (visible in the dashboard).
`uploader_id`	No	Force a specific uploader configuration when the key owns multiple uploaders.
`xmp_*`	No	XMP fields—see the metadata section below.

JS
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('metadata', JSON.stringify({ gallery: 'seniors', sequence: 12 }));
formData.append('xmp_title', 'Sunset Portrait');

const response = await fetch('https://tonta.io/uploader/upload.php', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData
});
const result = await response.json();
console.log(result.link);
            

Response

JSON
{
  "success": true,
  "id": "rT2F6Dn",
  "link": "https://files.tonta.io/rT2F6Dn.jpg",
  "sfname": "rT2F6Dn_1920.jpg",
  "size": 245632,
  "versions": [
    {
      "label": "Web",
      "filename": "rT2F6Dn_1920.jpg",
      "url": "https://files.tonta.io/rT2F6Dn_1920.jpg",
      "size": 245632,
      "dimensions": "1920x1280",
      "quality": 85,
      "format": "webp"
    }
  ],
  "original": {
    "filename": "rT2F6Dn.jpg",
    "url": "https://files.tonta.io/rT2F6Dn.jpg",
    "size": 3610442
  }
}
            

All asset URLs point to the Backblaze bucket at files.lilassistance.com. If originals are disabled, the original block is omitted and link points to the first processed version.

Delete API

Use the delete endpoint to remove files created by a given uploader. Requests must include the same X-API-Key used for uploads.

Method	Endpoint	Description
POST	`https://tonta.io/uploader/delete.php`	Delete by `smallid`, `smallids`, or base `id`

CURL
curl -X POST https://tonta.io/uploader/delete.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
        "smallids": ["rT2F6Dn_1920.jpg", "rT2F6Dn_1024.jpg"]
      }'
            

Alternatively, pass { "id": "rT2F6Dn" } to remove every version created for that base ID. The endpoint responds with:

JSON
{
  "success": true,
  "deleted": 2,
  "requested": 2,
  "errors": []
}
            

Metadata & XMP

Toggle “XMP Metadata Embedding” inside the uploader’s advanced settings to permanently embed caption data into image files. Supported fields:

Field	XMP Property	Notes
`xmp_title`	`dc:title`	Human-readable title
`xmp_description`	`dc:description`	Caption/alt text
`xmp_keywords`	`dc:subject`	Comma-separated keywords
`xmp_creator`	`dc:creator`	Photographer or studio
`xmp_copyright`	`dc:rights`	Copyright string
`xmp_custom_*`	Custom namespace	Any additional `xmp_custom_field` values are stored verbatim.

If XMP embedding is disabled, these fields are ignored but you can still store structured metadata via the metadata JSON payload for dashboard use.

Video Webhook

Tonta can hand off large video uploads to Modal for processing. When enabled, Modal calls our webhook at https://tonta.io/api/video-webhook.php, which in turn updates the uploader record. If you need your own webhook, hook into the dashboard’s onUploadComplete callback and forward the result payload to your system—there is no user-managed webhook service yet.

Troubleshooting

Common errors

401 Invalid API key: ensure you copied the key from the uploader you are targeting.
403 Domain not allowed: add the site’s origin to the uploader’s allowed domains.
File exceeds upload_max_filesize: increase the uploader’s max size or compress before upload.
Storage limit exceeded: upgrade your plan or delete files via the dashboard/delete API.

Server-side logs live at /home/runcloud/webapps/tonta/error.log if you need deeper diagnostics.

Tonta API & Embedding Guide