Skip to main content
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 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. 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:
  • 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:
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 as parts.