upload_url, then submit a session with its upload_id.
Uploading is free. No credit is held until you submit the session (see Billing).
Create an upload
A video upload can be up to 20 GB, but a session accepts more than 10 GB only with
fps: 60. See Limits.
Send the file
PUT the file to upload_url. Don’t send your Hooper API key there.
-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. 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:
- 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. ItsRangeheader (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
200or201.
Resume an interrupted transfer
If aPUT fails partway (a dropped connection, a timeout, a 5xx), ask what is stored before you send anything else:
- Retry
5xxand429responses with exponential backoff. - A transfer can resume at any time within the 7 days, including after your app restarts. Keep the
upload_id,upload_urland 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 finalPUT. 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:
size is a string. md5Hash and crc32c are base64.
The submit. POST /v1/sessions checks the stored file before it holds any credit:
There’s no separate event for a finished upload. The next event is
session.processed or session.failed (see Webhooks). 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 fails with video_too_large or video_fps_too_low, and nothing is charged.
Retries and duplicates
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).
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 asparts.