> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hooper.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploads

> Send a video file to Hooper, resume a broken transfer, and confirm Hooper has it.

Upload a file when your video isn't at a public URL. It takes three requests: create an upload, send the file to its `upload_url`, then [submit a session](https://developer.hooper.gg/sessions.md#sources) with its `upload_id`.

Uploading is free. No credit is held until you submit the session (see [Billing](https://developer.hooper.gg/billing.md)).

## Create an upload

```bash theme={null}
curl https://zeus.hooper.gg/v1/uploads \
  -H "Authorization: Bearer $HOOPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "content_type": "video/mp4", "size": 2147483648 }'
```

```json theme={null}
{ "id": "up_3f9a1c2b7e5d4a08", "object": "upload",
  "upload_url": "https://storage.googleapis.com/upload/storage/v1/b/…",
  "content_type": "video/mp4", "size": 2147483648, "expires_in_seconds": 604800 }
```

| Field | Notes |
| - | - |
| `content_type` | `video/mp4` (default) or `video/quicktime`. Images for [branding](https://developer.hooper.gg/sessions.md#branding) use `image/png`, `image/jpeg` or `image/webp`. |
| `size` | The file's exact length in bytes. `upload_url` accepts exactly that many. |
| `upload_url` | Where you send the file, always on `https://storage.googleapis.com`. A browser can send to it from any origin (CORS). It carries its own authorization, so keep it private and out of your logs. |
| `expires_in_seconds` | How long `upload_url` accepts bytes: 7 days. The stored file doesn't expire. |

A video upload can be up to 20 GB, but a session accepts more than 10 GB only with `fps: 60`. See [Limits](https://developer.hooper.gg/sessions.md#limits).

## Send the file

`PUT` the file to `upload_url`. Don't send your Hooper API key there.

```bash theme={null}
curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" -T game.mp4
```

`-T` streams the file from disk. `--data-binary @game.mp4` would read the whole video into memory first.

A `200` or `201` means the whole file is stored.

`upload_url` is a Google Cloud Storage [resumable upload](https://cloud.google.com/storage/docs/performing-resumable-uploads). One `PUT` works for most files. For a large file or an unreliable connection, send it in chunks, so a dropped connection costs one chunk instead of the whole file:

```bash theme={null}
# bytes 0–8,388,607 (the first 8 MiB) of a 2,147,483,648-byte file
curl -X PUT "$UPLOAD_URL" -H "Content-Range: bytes 0-8388607/2147483648" -T game.mp4.part0
```

* Every chunk except the last must be a multiple of 256 KiB (262,144 bytes). Chunks of 8 to 32 MiB work well.
* Each chunk before the last returns `308`. Its `Range` header (`bytes=0-N`) says what is stored. Send the next chunk from byte N+1, even if your last chunk ended later.
* The last chunk returns `200` or `201`.

## Resume an interrupted transfer

If a `PUT` fails partway (a dropped connection, a timeout, a `5xx`), ask what is stored before you send anything else:

```bash theme={null}
curl -X PUT "$UPLOAD_URL" -H "Content-Length: 0" -H "Content-Range: bytes */2147483648"
```

| Response | What to do |
| - | - |
| `308` with `Range: bytes=0-N` | Send the rest of the file, from byte N+1. |
| `308` with no `Range` | Nothing is stored yet. Send the file from byte 0. |
| `200` or `201` | The file is complete. Submit the session. |
| `404` or `410` | `upload_url` has expired. Create a new upload and send the file from byte 0. |

* Retry `5xx` and `429` responses with exponential backoff.
* A transfer can resume at any time within the 7 days, including after your app restarts. Keep the `upload_id`, `upload_url` and file path until the session is submitted.
* An upload you never finish is never used and costs nothing.

## Confirm Hooper has the file

Two responses come from Hooper rather than from your app.

**The final `PUT`.** Hooper's storage returns `200` or `201` only once it holds every byte. The body describes the stored file, so you can compare it with yours:

```json theme={null}
{ "name": "…/video.mp4", "size": "2147483648", "md5Hash": "kH7x…==", "crc32c": "n4Rd…==", "…": "…" }
```

`size` is a string. `md5Hash` and `crc32c` are base64.

**The submit.** `POST /v1/sessions` checks the stored file before it holds any credit:

| Response | Meaning |
| - | - |
| `409 upload_incomplete` | The file hasn't finished uploading, or is empty. Finish the `PUT`, then resubmit. |
| `400 video_too_large` | The file is over the size limit. Nothing is held, and the upload is deleted. |
| `201` with `status: "queued"` | Hooper has the video and accepted it. |

There's no separate event for a finished upload. The next event is `session.processed` or `session.failed` (see [Webhooks](https://developer.hooper.gg/webhooks.md)). Submit reads the upload's resolution from its header and refuses one over 2K with `400 video_too_large` (the upload is deleted). Frame rate is measured when processing starts. A video outside the [limits](https://developer.hooper.gg/sessions.md#limits) fails with `video_too_large` or `video_fps_too_low`, and nothing is charged.

## Retries and duplicates

| What was lost | What to do |
| - | - |
| The response to `POST /v1/uploads` | Create another upload. Creating one takes no `Idempotency-Key` and is safe to repeat. The first can't be looked up or listed, and an unused upload costs nothing. |
| The connection during the `PUT` | [Resume the transfer](#resume-an-interrupted-transfer). |
| The response to `POST /v1/sessions` | Send the same request again with the same `Idempotency-Key`. You get the original session back, not a second one. |

Always send an `Idempotency-Key` on `POST /v1/sessions`. Your own game id works well. A submit doesn't use up an upload, so you can resubmit it, for example after `insufficient_credits`. That also means a resend **without** a key creates a second session and holds credit for it again. Keys are kept for 24 hours (see [Idempotency](https://developer.hooper.gg/sessions.md#idempotency)).

Put your own game id in the session's `metadata` as well. Every session that `GET /v1/sessions` returns includes it, so you can match sessions to your games later.

## Several files for one game

Upload each file, then submit them together as [`parts`](https://developer.hooper.gg/sessions#sources).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.