File di grandi dimensioni

POST https://api.kennmarq.com/v1/uploads

Una richiesta all’API contiene al massimo 4 MB. Per un file più grande, fino a 25 MB (una clip da marcare fino a 1 GB), caricalo prima con un upload, direttamente sul nostro storage a Zurigo, poi indica l’upload invece di inviare il file. Gli SDK JavaScript e Python lo fanno da soli.

Come funziona

Richiedi un upload con la dimensione del file: {"bytes": 12345678}.
Invia il file con PUT all’url che ricevi, con i suoi headers, entro 15 minuti.
Indica l’upload in upload al posto di file su /v1/mark, /v1/check o /v1/verify, oppure in input_upload al posto di input su /v1/mark.

curl

# 1. The upload, for the file's size
curl https://api.kennmarq.com/v1/uploads \
  -H "Authorization: Bearer $KENNMARQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"bytes\": $(wc -c < render.png)}"
# → {"object":"upload","id":"up_…","url":"https://…","method":"PUT","headers":{"Content-Length":"…"},…}

# 2. The file, to the url (no Authorization header: the URL is the permission)
curl -X PUT --upload-file render.png "$UPLOAD_URL"

# 3. The call, naming the upload
curl https://api.kennmarq.com/v1/mark \
  -H "Authorization: Bearer $KENNMARQ_API_KEY" \
  -F upload=up_… -F source=created \
  -o render.marked.png

Richiesta

application/json con un solo campo, bytes: la dimensione del file, da 1 byte a 1 GB (1.073.741.824 byte). Ogni chiamata applica ai file che legge il proprio limite: 25 MB (26.214.400 byte), e 1 GB per una clip da marcare; una chiamata che indica un upload più grande risponde 413 payload_too_large. Serve una chiave con l’ambito mark o check. Richiedere un upload conta tra le chiamate al minuto dell’organizzazione, mai tra le sue marcature; una chiave può avere 100 upload in attesa contemporaneamente.

Risposta

201, application/json:

Campi di un upload
Campo	Valore
`object`	"upload"
`id`	L’ID dell’upload (up_…): indicalo nel campo upload della chiamata.
`bytes`	La dimensione che hai dichiarato; il file deve avere esattamente questa lunghezza.
`url`	Dove inviare il file con PUT: il nostro storage a Zurigo. L’URL stesso è l’autorizzazione, quindi non inviare alcun header Authorization.
`method`	"PUT"
`headers`	Gli header che la PUT deve contenere: Content-Length, per cui l’URL è firmato.
`url_expires_at`	L’URL funziona per 15 minuti.
`expires_at`	L’upload si può usare per un’ora; poi, se non è stato usato, viene eliminato.

Le regole

Un upload funziona una sola volta, entro un’ora, con la chiave che lo ha creato. Un’altra chiave, una seconda chiamata o una chiamata oltre l’ora ricevono 404 upload_not_found.
La PUT deve inviare esattamente la dimensione dichiarata; qualsiasi altra viene rifiutata. Una chiamata che indica un upload il cui file non è ancora arrivato riceve 400 invalid_request.
Una chiamata che non riesce per un motivo suo (un refuso in un’opzione, il nostro servizio momentaneamente non disponibile) lascia l’upload per il nuovo tentativo. Una chiamata che lo ha usato, o che ha rifiutato ciò che contiene (un file che non accetta, o bloccato dal controllo di sicurezza), lo consuma. Il job di una clip trattiene il suo upload finché non è finito; dopo un errore da parte nostra, l’upload torna utilizzabile per la sua ora.
Su /v1/verify, che non richiede alcuna chiave per un file inviato nella richiesta, per indicare un upload serve la chiave che lo ha creato.

Il file di un upload viene eliminato non appena la chiamata lo ha usato, oppure quando scade senza essere stato usato, un’ora dopo la sua creazione. Come ogni file che ci invii, viene usato solo per quella chiamata.

Errori

Errori di POST /v1/uploads
Stato	Codice	Quando
400	`invalid_request`	bytes manca, non è un numero intero o è inferiore a 1.
400	`unknown_field`	Un campo diverso da bytes.
401	`missing_api_key, invalid_api_key, api_key_revoked`	Vedi la pagina Autenticazione.
403	`insufficient_scope, ip_not_allowed`	La chiave non ha né l’ambito mark né l’ambito check, oppure l’indirizzo non è tra gli IP consentiti.
413	`payload_too_large`	bytes supera 1 GB.
415	`unsupported_media_type`	Il body non è inviato come application/json.
429	`rate_limited`	Troppe chiamate in questo minuto, oppure questa chiave ha già 100 upload in attesa; riprova dopo i secondi indicati da Retry-After.
503	`storage_unavailable`	Gli upload sono momentaneamente non disponibili. Riprova.

Il body degli errori segue il formato comune.