> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/overview/concepts/projects-and-uploads/.

# Projects and uploads

A project is one recording: create it, upload the file to Diffio's media host with its `upload_token`, then run generations on it. The upload goes in parts of `part_size_bytes`; the project checks the file and becomes `ready`.

## How it works

1. `awaiting_upload`: created; `upload` holds the token and requests
2. `preparing`: the file arrived and is being checked
3. `ready`: generations run; `project.ready` webhook

- from `preparing`: `failed`, the file could not be read; `project.failed` webhook

**Project `status`. A generation requested with the project waits in `queued` until `ready`.**

Webhooks `project.ready`, `project.failed` ([Webhooks](https://diffio.ai/docs/developers/webhooks/))

## Limits

| Limit | Value |
| --- | --- |
| File size | up to 2 GB (2,147,483,648 bytes); larger is `413 upload_too_large` |
| Media length | no limit |
| Part size | 32 MiB (`33554432` bytes); every part but the last |
| Upload token | 24 hours (`upload.expires_at`); `POST …/upload` gives a new one |
| Ready without `upload/complete` | about 30 seconds after the media host has the file |
| `upload/complete` check | up to 180 seconds inside the request |
| metadata | 50 keys; keys up to 40 characters, values up to 500 |
| Idempotency-Key | up to 255 characters, per account and end user |
| List page | `limit` 1 to 100, default 20, newest first |

## Build with it

- Guide [Podcast cleanup in a SaaS app](https://diffio.ai/docs/developers/guides/saas-podcast-cleanup/)

- [`POST /projects`](https://diffio.ai/docs/api-reference/create-project/)
- [`POST /projects/{project_id}/upload`](https://diffio.ai/docs/api-reference/reopen-project-upload/)
- [`POST /projects/{project_id}/upload/complete`](https://diffio.ai/docs/api-reference/complete-project-upload/)
- [`GET /projects/{project_id}`](https://diffio.ai/docs/api-reference/get-project/)
- [`GET /projects`](https://diffio.ai/docs/api-reference/list-projects/)
- [`DELETE /projects/{project_id}`](https://diffio.ai/docs/api-reference/delete-project/)

## Related pages

- Previous: [End users](https://diffio.ai/docs/overview/concepts/end-users/): Send Diffio-End-User with each request to keep every customer's projects, usage and events apart under one API key.
- Next: [Generations](https://diffio.ai/docs/overview/concepts/generations/): A generation is one restore of a project with one model; follow its status and stage, then read its media.
