# 姿勢分析 API（β）はどう使い始めればいいですか？

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

URL: https://shiseinavi.com/guides/posture-analysis-api-quickstart
更新日: 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度しか表示されません**

```bash
export SNV_KEY="snv_xxxxxxxx_..."
BASE=https://posture-api.shiseinavi.com
```

## 2. 疎通を確認する

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

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

## 3. 顧客を登録する

```bash
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枚を送って分析する

```bash
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）の枠に収めて分析します（[写真の条件](https://shiseinavi.com/docs/api#photos)）。

## 5. 結果を取得する

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

`analysis_status` が `completed` になると、スコア・評価・判定項目・AI アドバイスが入ります。この診断は店舗の画面の診断履歴・結果画面・手渡し PDF にも載ります。待たずに通知を受けたいときは [Webhook](https://shiseinavi.com/guides/receive-analysis-webhook) を使います。

## 分析の回数について

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

## 関連

- [API ドキュメント（β）](https://shiseinavi.com/docs/api)
- [エンドポイント一覧](https://shiseinavi.com/docs/api#endpoints)
- [分析完了の Webhook を受け取るには？](https://shiseinavi.com/guides/receive-analysis-webhook)

---

姿勢ナビ（運営: 株式会社Saucer）は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。
