アップロード

direct または multipart upload session を作成し、storage bytes を送り、処理を完了します。

このガイドでは、upload session を作成し、動画 bytes を送信し、処理が完了するまで監視する方法を説明します。

upload flow は 2 つの permission を使います。UPLOAD_VIDEOS は upload session operation に、READ_VIDEOS は processing status を返す video resource に使います。動画 bytes は API が返す短時間有効な storage target に直接送ります。

Session を作成する

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/videos" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-create-01" \
  -d '{
    "filename": "warehouse-inspection.mp4",
    "file_size": 157286400
  }'

request には、upload 前に caller が知っている元の filename と正確な file_size だけを含めます。content type は server が管理し、duration は processing 中に測定します。upload 方式は常に自動選択され、200 MiB 以下は 1 回の direct PUT、それより大きい動画は multipart upload になります。方式の希望は送らないでください。

response には public video_id、選択された strategy、session state、expiry、byte counter、target または targets が含まれます。storage target の method は小文字の enum token put です。これは storage request に HTTP PUT を使う意味です。

Direct upload

expires_at より前に、返された target をそのまま使ってください。

curl --fail-with-body -X PUT "$TARGET_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @warehouse-inspection.mp4

target の headers map にある各 key と value を、返されたとおりそのまま送ってください。header map の key は大文字小文字を含めて verbatim です。名前を変更したり snake_case に変換したりしないでください。DeepFrame API key を storage に送らないでください。

Multipart upload

session は targets と chunk_size を返します。各 part を target に upload してください。target が expire した場合は新しい target を要求してください。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID/upload/targets" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-targets-01" \
  -d '{"part_numbers":[1,2,3]}'

storage の ETag を quote を含めてそのまま記録してください。

curl --fail-with-body -X PUT "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID/upload/parts" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"part_number":1,"etag":"\"etag-part-1\""},{"part_number":2,"etag":"\"etag-part-2\""}]}'

同じ ETag の receipt を再送しても安全です。同じ part に異なる ETag を送ると拒否されます。

Upload を完了する

completion body は {} です。API は processing 前に file_size と storage object を比較します。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID/upload/complete" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upload-complete-01" \
  -d '{}'

202 response は動画が processing に入ったことを示します。index 完了は示しません。

Processing を監視する

READ_VIDEOS を使って GET /api/v1alpha1/videos/{video_id} を呼んでください。

curl --fail-with-body "$BASE_URL/api/v1alpha1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY"

video status は queued、processing、completed、failed です。進捗率は progress、失敗時は nested error object で確認します。upload session state と video processing status は別です。error_message は deprecated な field で、curated された error detail を繰り返すだけです。詳細はエラーを参照してください。

GET /api/v1alpha1/videos/{video_id}/upload は upload session を返し、UPLOAD_VIDEOS を使います。DELETE /api/v1alpha1/videos/{video_id}/upload は open session を中止し、204 を返します。

Retry ルール

session create、target refresh、completion には Idempotency-Key を使ってください。PUT /videos/{video_id}/upload/parts に idempotency header はありません。同じ ETag を再送する receipt contract が idempotent です。idempotency key の再利用時に body を変更しないでください。