Uploading your data
Before anyone can label anything, the data has to be in the project. This page assumes you have never done that before. It explains the four ways in, how to pick one, and the two errors people hit most.
First, the one idea that explains everything
Your project has a labeling setup that names the things it expects.
If it says value="$audio", every task must supply something called
audio. If it also shows a prompt, value="$text", then every task must
supply both audio and text.
That single fact decides how you upload:
| Your setup asks for | Upload this way |
|---|---|
| One thing (just audio, just an image, just a video) | Drag the files straight in |
| Two or more things (a prompt and a recording, an image and a caption) | A JSON or CSV file that names each field |
Drag a folder of MP3s into a project that also shows a written prompt and the upload is refused, with a message about having more than one data key. Nothing is broken — the platform simply cannot guess which field your files belong to. Use JSON or CSV and say so explicitly.
The four ways in
1. Drag and drop files
Open the project, choose Import, and drop files on the box or click to browse. You can select many files at once.
Best for: a first project, a demo, or data that only exists on your laptop.
Accepted file types:
| Kind | Extensions |
|---|---|
| Audio | .mp3 .wav .flac .m4a .ogg |
| Video | .mp4 .webm |
| Images | .jpg .jpeg .png .gif .bmp .svg .webp, and .heic .heif .tif .tiff .avif (converted to JPEG, or PNG with transparency, on upload) |
| Documents | .pdf .html .htm .xml |
| Data files | .csv .tsv .txt .json |
Direct upload is slower than connecting a bucket, but it is built for a poor connection:
- Each file uploads on its own. One that fails does not undo the others.
- A file that fails because the connection dropped is sent again by itself, after a short wait that grows with each attempt. If the browser reports no connection, the upload waits for it to come back.
- Files of 4 MB or more go up in pieces sized to the speed of the link (from 256 KB to 8 MB each). After a drop only the piece in flight is sent again, not the whole file.
- Nothing becomes a task until you press Import, so an interrupted session leaves no half-made tasks.
Keep the Import page open until every card has finished: closing the tab stops the uploads still in progress.
2. A JSON or CSV file
Instead of the media itself, you upload a small file that describes the tasks — including a web address for each media file.
[
{"audio": "https://example.org/clips/001.wav", "prompt": "Read this sentence aloud"},
{"audio": "https://example.org/clips/002.wav", "prompt": "Read this sentence aloud"}
]
The key names (audio, prompt) must match the $names in your
labeling setup. The same thing as CSV, one column per field:
audio,prompt
https://example.org/clips/001.wav,Read this sentence aloud
Best for: anything with more than one field, and any dataset where the media is already online.
3. Paste a link
The URLs tab takes web addresses and fetches them for you. Handy for a handful of files already on the web.
4. Connect cloud storage — the one to use for real datasets
Point the project at a storage bucket (Amazon S3, Google Cloud Storage, Azure Blob) or a folder on the server, and press Sync.
This is the method to use once you have more than a few dozen media files, and it is worth understanding why: your files are never copied into the platform. Tasks simply point at the objects where they already live, and each file is fetched only when an annotator opens it.
That means:
- No size ceiling to work around.
- No second copy of your data, so no paying to store it twice.
- Add more later by dropping files in the bucket and syncing again.
Set-up is in Cloud storage.
"I have one three-hour recording" — split it here
Upload it, press Split into clips on its card, mark the cut points while it plays (or let silence detection suggest them), and turn the clips into tasks. See Splitting recordings into clips.
"I have 300 videos" — do this
Do not push them through the browser. Put them in a bucket and connect it (method 4), or host them somewhere and import a JSON list of their addresses (method 2).
If you must upload directly, know the limits you are working against:
| Limit | Value |
|---|---|
| One request to the server | 24 MB — larger files switch to resumable pieces automatically |
| Largest single file | 250 MB |
| Storage per project | set by your organisation's plan (see below); unlimited when no plan cap is set |
Every file travels in its own request. Drop 40 clips and you get 40 small uploads, three at a time, each with its own progress bar showing the bytes sent so far. Files of 24 MB and more go up in resumable 8 MB pieces with retries, so a dropped connection costs you the current piece, not the whole file.
A failed file never takes the others with it. If one clip is refused (wrong type, empty, network drop, quota), it moves to its own red card saying what happened, with a Dismiss button. The files that already landed stay in the list and can be imported as normal; drop the failed one again to retry.
Storage is checked before anything is sent. Each project has a storage allowance set by the organisation's plan. Before uploading, the import page asks the server how much of this project's allowance is left and refuses the whole drop up front if the files would not fit, so you never end up with half a batch imported. Organisation owners and admins see the allowance and the heaviest project on Organization → Overview → Plan and usage, and can request an increase from there. Connected cloud storage is never copied, so it does not count.
Direct upload is still slower and more fragile than connecting a bucket.
Errors, and what they mean
"Your label config has more than one data key and direct file upload supports only one." You dragged media into a project that expects more than one field. Upload a JSON or CSV file instead that names each field — see the table at the top.
"This project expects images, but 'clip.mp3' is not one." The file type does not match what your labeling setup asks for. The message lists the extensions this project accepts. Either you picked the wrong files, or the labeling setup is wrong — if this project really is meant for audio, open Labeling setup and change the tag, then import again. Nothing was uploaded, so there is nothing to clean up.
"'clip.mp4' is empty (0 bytes)." The file contains no data — usually a transfer that was interrupted, or a placeholder that was never filled in. Check the file opens on your own machine before importing it again.
"These files add up to X but this project has only Y of its storage allowance left." Shown before anything is uploaded. Remove data you no longer need, connect cloud storage instead of uploading (nothing is copied, so it does not count), or ask an organisation owner or admin to Request an increase on the organisation overview.
"This project has used X GB of its Y GB storage limit." The server-side version of the same check, for uploads that arrive by API or when the pre-check could not run. Same remedies.
"Not uploaded: Network error during upload." The connection dropped while this one file was being sent. The other files in the drop are unaffected; drop this file again to retry.
"Every task plays the same audio / shows the same image." Fixed in September 2026 (the app's offline cache keyed uploaded media by path only, and on cloud storage every upload shares one path). If you still see it, reload the page once so the browser picks up the new version; nothing about your files is wrong.
Checklist before you import
- Open Labeling setup and note every
$nameit uses. - One name → drag files in. More than one → prepare JSON or CSV.
- More than ~50 media files → connect cloud storage instead.
- Import a handful first and open one task. If it displays correctly, import the rest. This costs two minutes and saves re-importing hundreds of wrongly-shaped tasks.