GUIDE

姿勢分析 API(β)はどう使い始めればいいですか?

姿勢ナビの API(β)は、店舗の管理画面で発行した API キーを Bearer 認証に付けて呼び出します。疎通確認(GET /v1/ping)のあと、顧客を登録し、正面と側面の写真2枚を POST /v1/examinations に送ると分析が始まり、20〜60 秒ほどで結果を取得できます。β版のため、予告なく仕様を変更する場合があります。

β版です。予告なく仕様を変更する場合があります。 更新日: 2026-10-29

用意するもの

  • 姿勢ナビを契約している店舗の管理画面に、企業管理者(オーナーを含む) でログインできること
  • curl が使える環境(Mac・Linux のターミナル、Windows の PowerShell など)
  • 試し用の写真2枚(正面・側面。全身が写ったもの)

1. API キーを発行する

  1. 管理画面の右上のメニューから「API設定 β」(または「事業者設定」→「API連携」)を開きます
  2. 「キーを発行」を押します(キーを発行すると、外部 API は自動で有効になります)
  3. 名前(用途)・スコープ・有効期限を選びます。試すだけなら read:clients・write:clients・read:examinations・write:examinations で足ります
  4. 表示されたキー(snv_...)をコピーして保管します。1度しか表示されません
export SNV_KEY="snv_xxxxxxxx_..."
BASE=https://posture-api.shiseinavi.com

2. 疎通を確認する

curl -s "$BASE/v1/ping" -H "Authorization: Bearer $SNV_KEY"

キーが有効なら、企業・スコープ・店舗の範囲が返ります。401 unauthorized のときは、キーの写し間違い・失効・「外部 API を有効にする」が OFF になっていないかを確かめてください。

3. 顧客を登録する

KEY=$(uuidgen)   # この依頼の冪等キー(再送でも同じ値を使う)
curl -s -X POST "$BASE/v1/clients" \
  -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"テスト 太郎","external_id":"CRM-0001"}'

通信が切れたときは、同じ KEY で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります(KEY は依頼1回ごとに1度だけ作り、再送では作り直さない)。

返ってきた data.uid(CL...)が顧客の ID です。

4. 写真2枚を送って分析する

KEY=$(uuidgen)   # この依頼の冪等キー(再送でも同じ値を使う)
curl -s -X POST "$BASE/v1/examinations" \
  -H "Authorization: Bearer $SNV_KEY" -H "Idempotency-Key: $KEY" \
  -F client_uid=CL12345678 \
  -F "images[standing]=@front.jpg" -F "images[standing_side]=@side.jpg"

通信が切れたときは、同じ KEY で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります(KEY は依頼1回ごとに1度だけ作り、再送では作り直さない)。

202 と poll_url が返れば受付完了です。写真は撮影画面と同じ 3:4(480×640)の枠に収めて分析します(写真の条件)。

5. 結果を取得する

curl -s "$BASE/v1/examinations/EM12345678" -H "Authorization: Bearer $SNV_KEY"

analysis_status が completed になると、スコア・評価・判定項目・AI アドバイスが入ります。この診断は店舗の画面の診断履歴・結果画面・手渡し PDF にも載ります。待たずに通知を受けたいときは Webhook を使います。

分析の回数について

API で受け付けた分析も、画面で撮影したときと同じく 店舗の月間分析回数 と 企業の AI アドバイス残数 を使います。上限に達すると 429 monthly_limit_exceeded になります。

関連