Tools

Resumable Upload#

POST /censor, POST /transcribe, POST /fix, POST /extract and POST /sync take one request of up to 100 MB. For a larger file, or a connection that drops, send the file in chunks and use its upload_id. It is for paid keys with a balance: an upload needs at least 10 requests left to start, and nothing is stored otherwise. Every call needs the key that started the upload, in the Authorization: Bearer YOUR_KEY header. Another key gets 404.

StepCallAnswer
StartPOST /upload { "size": 1234, "sha256": "..." }{ upload_id, chunk_bytes, max_chunk_bytes, expires_in }
Send a chunkPUT /upload/{id}?offset=N{ received, size }
Check progressGET /upload/{id}{ received, size, complete }
FinishPOST /upload/{id}/complete{ upload_id, size, sha256 }
Give upDELETE /upload/{id}{ deleted: true }
Start the jobPOST /censor?upload_id={id}The usual job answer

Start the job with upload_id and the usual options as query parameters, or send them as a JSON body (Content-Type: application/json). That is also how ranges_file is sent, as text of up to 5 MB. Idempotency-Key works there as on any job: a new key for each new job, the same key only to retry the same request.

POST /transcribe, POST /fix, POST /extract and POST /sync take upload_id too, with no body: send ?key=YOUR_KEY&upload_id=ID and the options as query parameters. On these four routes the key goes in the query. For /fix the subtitle comes from url, or from id and language. /transcribe and /fix start a job and take Idempotency-Key; /extract and /sync answer directly. A started job or a successful answer spends the upload; a refusal (a 402 or another 4xx) leaves it for a retry.

Rules#

  • size is the file's size in bytes. For a file over 100 MB, sha256 (64 hex digits) is required at the start. Below that it is optional, and it can also be sent to complete. A paid key can upload up to the server's media limit (2 GB). A larger size is 413.
  • Send chunk_bytes (8 MB) at a time; a chunk can be up to max_chunk_bytes (32 MB). Chunks are written in order: offset must equal the bytes already received. A wrong offset is 409 with received: carry on from there.
  • A chunk that is cut off stores nothing (400 with received). Send it again.
  • One chunk at a time per upload: a second one at the same time is 409 with retry-after.
  • A key can have 3 unfinished uploads (6 GB declared in all). More is 429 until one is finished, used or deleted; finished uploads don't count. When the server is short of disk space, a start is 503 with retry-after.
  • complete checks that every byte arrived and that the SHA-256 matches the one sent at the start or at the end. A mismatch deletes the upload (422 hash_mismatch): send it again.
  • An upload idle for 6 hours is deleted, and a finished one 2 hours after its last use. Within that time the same upload_id can start a job again if the first try was refused (a 402, then a retry), so the file is sent once. Once a job has started, the upload is deleted: send a new upload for another job.
  • The job is charged exactly as if the file had been sent in one request.

With curl#

SIZE=$(stat -c%s movie.mkv)
SHA=$(sha256sum movie.mkv | cut -d' ' -f1)
ID=$(curl -s -X POST "https://sub.wyzie.io/upload" \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d "{\"size\":$SIZE,\"sha256\":\"$SHA\"}" | jq -r .upload_id)
 
split -b 8M -d -a 4 movie.mkv part.
OFFSET=0
for p in part.*; do
  curl -s -X PUT "https://sub.wyzie.io/upload/$ID?offset=$OFFSET" \
    -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/octet-stream" \
    --data-binary @"$p"
  OFFSET=$((OFFSET + $(stat -c%s "$p")))
done
 
curl -s -X POST "https://sub.wyzie.io/upload/$ID/complete" -H "Authorization: Bearer YOUR_KEY"
curl -X POST "https://sub.wyzie.io/censor?upload_id=$ID&level=strict" \
  -H "Authorization: Bearer YOUR_KEY" -H "Idempotency-Key: $(uuidgen)"

Resume After a Drop#

const KEY = 'YOUR_KEY';
const api = (p, init = {}) =>
  fetch(`https://sub.wyzie.io${p}`, {
    ...init,
    headers: { Authorization: `Bearer ${KEY}`, ...init.headers },
  });
 
async function upload(file, saved /* { id } from localStorage, or null */) {
  let id = saved?.id;
  if (!id) {
    const r = await api('/upload', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ size: file.size }),
    });
    ({ upload_id: id } = await r.json());
    localStorage.setItem(
      'wyzie-upload',
      JSON.stringify({ id, name: file.name, size: file.size }),
    );
  }
  let { received, complete } = await (await api(`/upload/${id}`)).json(); // where to resume
  while (!complete && received < file.size) {
    const end = Math.min(received + 8 * 1024 * 1024, file.size);
    const r = await api(`/upload/${id}?offset=${received}`, {
      method: 'PUT',
      body: file.slice(received, end),
    });
    if (r.ok) ({ received } = await r.json());
    else if (r.status === 409 || r.status === 400)
      ({ received } = await (await api(`/upload/${id}`)).json()); // resync, then carry on
    else throw new Error(`upload stopped: ${r.status}`);
  }
  const done = await (
    await api(`/upload/${id}/complete`, { method: 'POST' })
  ).json();
  return done.upload_id; // POST /censor?upload_id=...
}

After a reload, pick the same file again and call upload(file, saved) with what you saved: it asks the server how much it has and sends only the rest.

In the SDKs#

The SDKs do this for you: over 100 MB they send the file in chunks, reading it from disk a chunk at a time, and call the route with its upload_id at the same price. wyzie-lib 2.24.0 does it in censor, transcribe, fix and extractSubtitles, and syncSubtitle sends large media in chunks too. wyzie-go v1.10.0 does it in Censor, Transcribe, Fix and Extract, and the Python client 0.10.0 in censor, transcribe, fix and extract; neither has a sync call. Call uploadLarge, UploadLarge or upload_large yourself to keep the upload id and resume after a restart. A file that changed while it was sent is a hash mismatch error: send it again. In wyzie-mcp 0.10.0, censor_video_file, extract_subtitles and transcribe_file do the same for local files up to 2 GB.

import { openAsBlob } from 'node:fs';
import { uploadLarge, censor } from 'wyzie-lib';
 
const file = await openAsBlob('movie.mkv'); // read a chunk at a time, never whole into memory
const job = await censor(file, { level: 'strict' }); // over 100 MB: chunked upload, then the job
const id = await uploadLarge(file, {
  uploadId: saved ?? undefined,
  onUploadId: (x) => save(x),
});
f, _ := os.Open("movie.mkv")
job, err := c.Censor(ctx, f, wyzie.CensorOptions{Level: wyzie.LevelStrict})
st, _ := f.Stat()
id, err := c.UploadLarge(ctx, f, st.Size(), wyzie.UploadOptions{UploadID: saved, OnUploadID: save})
job = wyzie.censor("movie.mkv", level="strict")  # over 100 MB: chunked upload, then the job
uid = wyzie.upload_large("movie.mkv", upload_id=saved, on_upload_id=save)