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 キーを発行する
- 管理画面の右上のメニューから「API設定 β」(または「事業者設定」→「API連携」)を開きます
- 「キーを発行」を押します(キーを発行すると、外部 API は自動で有効になります)
- 名前(用途)・スコープ・有効期限を選びます。試すだけなら
read:clients・write:clients・read:examinations・write:examinationsで足ります - 表示されたキー(
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 になります。