メインコンテンツへスキップ
本ガイドは クイックスタート で $LYMO_KEY・$LYMO_BASE・$VIDEO を設定済みであることを前提とします。$LYMO_BASE は /platform までで、バージョン付きパスは /v1 配下です。
Platform API における長時間処理は、ステータスを自身で保持するドメインリソース としてモデル化されています。不透明なジョブ ID ではありません。該当リソースは現時点で 2 種類です。
  • POST /v1/videos/:id/analyses — 動画を分析
  • POST /v1/deals/:id/scorings — 案件をスコアリング
どちらも作成直後に 201 と status: "processing"、および安定した id を返します。完了はリソースをポーリングするか、Webhook を購読して取得してください。

​
ライフサイクル

POST   /v1/videos/:id/analyses           → 201 { id, status: "processing", ... }
GET    /v1/videos/:id/analyses/:id       → 200 { id, status: "processing" | "completed" | "failed", ... }
GET    /v1/videos/:id/analyses           → 200 { data: [履歴 ...] }

​
ステータス値

外部ステータスは、内部ワークフローの複数の状態を 3 値に集約したものです。
ステータス意味
processingキュー投入済み、または処理中
completed正常終了。result に結果が格納される
failed終端的な失敗。error: { code, message } が付与される
completed または failed に到達したリソースは、それ以上遷移しません。

​
完了結果の読み取り

分析やスコアリングが completed になると、同じ GET エンドポイントのレスポンスに result フィールドが加わります。フィールドごとの完全なスキーマは APIリファレンス タブを参照してください。概要は以下のとおりです。
  • 分析（Analyses） — result には要約セクション、チェックリスト評価（組織で有効な場合）、検出された営業イベントが含まれます。個別に取得したい場合は GET /v1/videos/:id/summary、.../checklist、.../events を使ってください。
  • スコアリング（Scorings） — result には案件に対して算出されたスコア因子が含まれます。GET /v1/deals/:id でも同じ因子を参照できます。
failed の場合は result の代わりに error: { code, message } が入ります。code は機械判読用の安定した文字列で、switch で分岐できます。message は人間向けの説明で、バージョン間で変わる可能性があります。 エンドツーエンドの処理時間は通常、分単位の範囲です。ポーリング間隔は 5〜10 秒で十分です。処理が本当に詰まった場合は内部のタイムアウトで failed に遷移するため、API 側がリソースを永遠に processing のままにすることはありません。

​
ポーリング

ANALYSIS=$(curl -s -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY" | jq -r .data.id)

while true; do
  STATUS=$(curl -s "$LYMO_BASE/v1/videos/$VIDEO/analyses/$ANALYSIS" \
    -H "Authorization: Bearer $LYMO_KEY" | jq -r .data.status)
  [ "$STATUS" != "processing" ] && break
  sleep 5
done

echo "Analysis finished with status: $STATUS"
ポーリング間隔は 5 秒を推奨します。429 レスポンスには Retry-After ヘッダーが付くので、即時再試行せず必ずこれに従ってください。

​
冪等性

POST リクエストでは Idempotency-Key ヘッダーを受け付けます。最初の 2xx レスポンスは 24 時間キャッシュされ、キーは (組織, メソッド, パス, キー, ボディハッシュ) の組で管理されます。再送時は同じレスポンスがそのまま返されます。 
curl -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 16)"
同じキーで異なるボディを送ると、キャッシュキーが一致しないため別の処理として扱われます。つまり、ペイロードが違う再送で想定外のレスポンスを受け取る事故は起きません。
元リソースが削除または再処理されていても、キャッシュされたレスポンスがそのまま返ります。新規リクエストとして強制したい場合は新しい Idempotency-Key を送ってください。キーが 256 文字を超えると 400 bad_request になります。
クライアントタイムアウトで POST の成否が曖昧になるような場面では、必ず冪等キーを使ってください。

​
ポーリングの代わりに購読する

本番ワークロードでは Webhook を登録して Lymo からの通知を受け取るのが推奨です。
  • video.analysis.completed
  • video.analysis.failed
案件スコアリング系イベント（deal.scoring.completed・deal.scoring.failed）は、SDK の型を安定させる目的でスキーマには定義されていますが、配信側はまだ実装されていません。現時点で購読しても通知は届きません。将来のリリースで有効化予定です。
Webhook の登録、署名検証、イベント一覧は Webhook を参照してください。