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.
| Step | Call | Answer |
|---|---|---|
| Start | POST /upload { "size": 1234, "sha256": "..." } | { upload_id, chunk_bytes, max_chunk_bytes, expires_in } |
| Send a chunk | PUT /upload/{id}?offset=N | { received, size } |
| Check progress | GET /upload/{id} | { received, size, complete } |
| Finish | POST /upload/{id}/complete | { upload_id, size, sha256 } |
| Give up | DELETE /upload/{id} | { deleted: true } |
| Start the job | POST /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#
-
sizeis 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 tocomplete. 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 tomax_chunk_bytes(32 MB). Chunks are written in order:offsetmust equal the bytes already received. A wrong offset is 409 withreceived: 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. -
completechecks 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 (422hash_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_idcan 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)