Fichiers volumineux

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

Une requête à l’API transporte au plus 4 Mo. Pour un fichier plus lourd, jusqu’à 25 Mo (jusqu’à 1 Go pour une vidéo à marquer), téléversez-le d’abord, directement dans notre stockage à Zurich, puis désignez l’envoi dans l’appel au lieu d’y joindre le fichier. Les SDK JavaScript et Python le font d’eux-mêmes.

Fonctionnement

1. Demandez un envoi en indiquant la taille du fichier : {"bytes": 12345678}.
2. Envoyez le fichier par PUT à l’url reçue, avec ses headers, dans les 15 minutes.
3. Indiquez l’envoi dans upload au lieu de file sur /v1/mark, /v1/check ou /v1/verify, ou dans input_upload au lieu de input sur /v1/mark.

# 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

Requête

application/json avec un seul champ, bytes : la taille du fichier, de 1 octet à 1 Go (1 073 741 824 octets). Chaque appel applique sa propre limite aux fichiers qu’il lit : 25 Mo (26 214 400 octets), et 1 Go pour une vidéo à marquer ; un appel qui indique un envoi plus volumineux répond 413 payload_too_large. Nécessite une clé avec la portée mark ou check. Demander un envoi compte dans les appels par minute de l’organisation, jamais dans ses marquages ; une clé peut avoir 100 envois en attente à la fois.

Réponse

201, application/json :

Les règles

• Un envoi ne sert qu’une fois, dans l’heure, avec la clé qui l’a créé. Une autre clé, un deuxième appel ou un appel plus tardif reçoit 404 upload_not_found.
• Le PUT doit envoyer exactement la taille déclarée ; toute autre taille est refusée. Un appel qui indique un envoi dont le fichier n’est pas encore arrivé reçoit 400 invalid_request.
• Un appel qui échoue pour une raison qui lui est propre (une faute de frappe dans une option, notre service momentanément indisponible) laisse l’envoi disponible pour la nouvelle tentative. Un appel qui l’a utilisé, ou qui a refusé son contenu (un fichier qu’il n’accepte pas, ou bloqué par le contrôle de sécurité), le consomme. La tâche d’une vidéo garde son envoi jusqu’à ce qu’elle soit terminée ; après un échec de notre côté, il redevient utilisable pendant son heure.
• Sur /v1/verify, qui ne demande aucune clé pour un fichier envoyé dans la requête, indiquer un envoi nécessite la clé qui l’a créé.

Erreurs

Les corps d’erreur suivent le format commun.