# 姿勢ナビ(全文) > Shiseinavi (姿勢ナビ) is a Japanese SaaS for fitness, pilates, chiropractic and esthetic studios: it analyzes posture from photos with AI and turns the result into a conversation with the customer. > A REST API (beta) lets studios register customers, send two photos for posture analysis and receive the results from their own systems or AI agents. Documentation below is in Japanese. 姿勢ナビ(運営: 株式会社Saucer)は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。 主な機能: - AI姿勢分析: 写真撮影だけで歪み・傾きを分析し、姿勢スコア・評価・気になるポイント(良好・注意・要改善)を表示 - 改善エクササイズ提案: 分析結果に合わせて、自宅でできる運動を動画で提案 - 自社製品提案: 分析結果に紐づけて、店舗のメニュー・物販をおすすめ - 未来姿勢: 改善しないまま放置した場合の姿勢リスクを可視化 - ゲストスキャン: 顧客登録をしていない方の姿勢分析もできる - AI解説サンプル生成: お客様への説明文を AI が作る。姿勢の知識がなくても、どのスタッフでも同じ説明ができる - 結果の渡し方: QR でスマホに残す、SNS 用画像、A4 の手渡し PDF(分析結果画面からダウンロード) - API(β): 顧客・診断の取得と登録、写真2枚を送っての姿勢分析と結果の取得、分析完了の Webhook、撮影画面・結果画面を開く埋め込み URL、集計。β版です。予告なく仕様を変更する場合があります。 料金: 月5,000円〜(店舗数・契約期間で変わるため、問い合わせで見積もり)。問い合わせ: 「無料お問い合わせ」 https://shiseinavi.com/contact 医療効果を保証するものではありません。分析は姿勢を「可視化」し、変化を確認するための道具です。 --- # 姿勢ナビ API(β)ドキュメント > 姿勢ナビの Company API(β)のリファレンスとクイックスタート。APIキーの発行、顧客の登録、写真2枚を送っての姿勢分析と結果の取得、分析完了の Webhook、埋め込み URL、エラー形式と流量制限。 URL: https://shiseinavi.com/docs/api 更新日: 2026-10-29 姿勢ナビ(運営: 株式会社Saucer)は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。 > **β版です。予告なく仕様を変更する場合があります。** エンドポイント・項目・制限値は、β期間中に変わることがあります。変更があったときは、このページと [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) を更新します。 姿勢ナビの Company API は、店舗(企業)が自分で発行した API キーで、自社のシステムや AI エージェントから姿勢ナビのデータを扱うための REST API です。 - **できること**: 顧客・診断の取得と登録、**正面・側面の写真2枚を送ると姿勢分析が走り、結果を取得できる**、分析の完了・失敗の Webhook 通知、診断の撮影画面・結果画面を自社アプリから開く埋め込み URL の発行、診断数・スコアなどの集計 - **AI から使う**: 仕様を [OpenAPI(YAML)](https://shiseinavi.com/openapi/company-api.yaml) で公開しています。AI エージェント(Claude Code、ChatGPT のカスタムアクションなど)に OpenAPI と API キーを渡せば、API をそのまま呼び出せます([AI エージェントから使う](#ai-agents)) - **AI 向けの要約**: [llms.txt](https://shiseinavi.com/llms.txt) / [llms-full.txt](https://shiseinavi.com/llms-full.txt)(このページの全文を含みます) ## 基本 | 項目 | 内容 | |---|---| | ベース URL | `https://posture-api.shiseinavi.com`(パスは `/v1/...`。`/api` のプレフィックスはありません) | | 認証 | `Authorization: Bearer snv_<8文字>_<64桁>`(店舗の管理画面で発行した API キー) | | 形式 | JSON(UTF-8)。書き込みの本文も `Content-Type: application/json`(写真の送信だけ multipart) | | 日時 | ISO 8601(UTC、末尾 `Z`)。日付は `YYYY-MM-DD` | | エラー | [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の `application/problem+json` | | 仕様 | [OpenAPI 3.0(YAML)](https://shiseinavi.com/openapi/company-api.yaml) | ## API キーの発行 API キーは、店舗が姿勢ナビの管理画面で発行します(企業管理者・オーナーの権限が必要です)。 1. 姿勢ナビの管理画面に、企業管理者(オーナーを含む)でログインします 2. 右上のメニューの「API設定 β」(または「事業者設定」→「API連携」)を開きます 3. 「キーを発行」から、名前(用途)・スコープ・有効期限を選んで発行します。分析完了の通知を受けたい場合は、Webhook の送信先 URL も入れられます(あとからでも設定できます) 4. 表示された API キー(`snv_...`)と Webhook の署名シークレットを、その場でコピーして保管します。**どちらも1度しか表示されません** - キーを発行すると「外部 API を有効にする」が自動で ON になります。OFF にすると、発行済みのすべてのキーがすぐに使えなくなります(ON に戻せば、失効していないキーは再び使えます) - 不要になったキーは「失効する」で止めます。直近の呼び出し(50件)と Webhook の配送履歴を画面で確認できます - キーで使える範囲は **キーのスコープ ∩ 発行したスタッフの今の権限** です。発行者が停止・削除・降格されると、そのキーも止まる(または狭まる)ので、退職者のキーは自動で使えなくなります - 担当店舗が限定されたスタッフが発行したキーは、その店舗のデータだけを扱えます(他店舗の詳細は 404、他店舗を条件に指定すると 422) ### スコープ | スコープ | できること | 発行者に必要な権限 | |---|---|---| | `read:clients` | 顧客の閲覧 | 全スタッフ | | `read:examinations` | 診断の閲覧 | 全スタッフ | | `read:settings` | 企業・店舗・スタッフ・判定レベルの閲覧 | 全スタッフ | | `read:reports` | 集計の閲覧 | 店舗管理者以上 | | `write:clients` | 顧客の登録・更新・削除 | 全スタッフ | | `write:examinations` | 写真を送っての新規分析、診断の更新(日付のみ)・削除 | 全スタッフ | | `write:settings` | 企業・店舗設定の変更 | 企業管理者(オーナーを含む) | | `embed` | 診断画面・マイページ・結果を開く URL の発行 | 全スタッフ | スコープが足りないと `403 insufficient_scope` になり、本文の `required_scopes` に必要なスコープが入ります。 ## クイックスタート(curl) 疎通確認 → 顧客の登録 → 写真2枚を送って分析 → 結果の取得、の順に進めます。 ```bash export SNV_KEY="snv_xxxxxxxx_..." # 発行した API キー(コードやチャットに直接貼らない) BASE=https://posture-api.shiseinavi.com ``` ### 1. 疎通確認 ```bash curl -s "$BASE/v1/ping" -H "Authorization: Bearer $SNV_KEY" # → {"data":{"company":{"uid":"CP12345678","name":"株式会社サンプル"},"scopes":["read:clients",...],"shop_uids":null,"key":{...}}} ``` どの企業・スコープ・店舗範囲で動くキーかが返ります(スコープ不要)。 ### 2. 顧客を登録する(`write:clients`) ```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":"山田太郎","email":"taro@example.com","external_id":"CRM-12345"}' # → 201 {"data":{"uid":"CL12345678", ...}} Location: .../v1/clients/CL12345678 ``` 通信が切れたときは、同じ `KEY` で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります(`KEY` は依頼1回ごとに1度だけ作り、再送では作り直さない)。 - `external_id` に自社システムの顧客 ID を入れておくと、`GET /v1/clients?external_id=CRM-12345` で引けます(他の顧客と重なると `409 conflict`) - `Idempotency-Key` を付けると、タイムアウト後に再送しても二重に登録されません ### 3. 写真2枚を送って分析する(`write:examinations`) ```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" # → 202 {"data":{"uid":"EM12345678","analysis_status":"pending","ai_advice":"enabled", # "poll_url":"https://posture-api.shiseinavi.com/v1/examinations/EM12345678", ...}} ``` 通信が切れたときは、同じ `KEY` で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります(`KEY` は依頼1回ごとに1度だけ作り、再送では作り直さない)。 `Idempotency-Key` は**必須**です。受け付けると `202` と `poll_url` が返り、サーバーが骨格検出 → 骨格線の描画 → 解析 → 採点 → AI アドバイスまで進めます。写真の条件は [分析に使う写真](#photos) を見てください。 ### 4. 結果を取得する(ポーリング、または Webhook) ```bash curl -s "$BASE/v1/examinations/EM12345678" -H "Authorization: Bearer $SNV_KEY" # analysis_status: pending → processing → completed | failed ``` - 所要時間は 20〜60 秒ほどです。ポーリングは 5 秒間隔程度にしてください - `completed` になると、スコア・評価・判定項目・AI アドバイスなどが入ります。画面で撮影した診断と同じく、顧客の診断履歴・結果画面・手渡し PDF にもそのまま載ります - AI アドバイスの有無は `ai_advice_requested`(true / false)で見分けてください。`ai_advice_result_status` は AI を使わない設定でも完了すれば `done` になります。`ai_advice_requested` は詳細(`GET /v1/examinations/{uid}`)だけに載り、一覧・Webhook の本文には含みません - 待ちたくない場合は [Webhook](#webhook) で完了・失敗の通知を受け取れます ### 5. (任意)結果画面を自社アプリから開く(`embed`) ```bash curl -s -X POST "$BASE/v1/clients/CL12345678/embed_tokens" \ -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \ -d '{"kind":"result","examination_uid":"EM12345678"}' # → {"data":{"url":"https://cp.shiseinavi.com/clients/CL12345678/login?token=...","kind":"result","expires_in":1800}} ``` 返った `url` を新しいタブで開くと、その顧客の結果画面が表示されます([埋め込み URL](#embed))。 ## エンドポイント一覧 | メソッド | パス | 内容 | スコープ | |---|---|---|---| | `GET` | `/v1/ping` | 疎通確認 | 不要 | | `GET` | `/v1/clients` | 顧客一覧 | `read:clients` | | `POST` | `/v1/clients` | 顧客の登録 | `write:clients` | | `GET` | `/v1/clients/{uid}` | 顧客詳細 | `read:clients` | | `PATCH` | `/v1/clients/{uid}` | 顧客の更新 | `write:clients` | | `DELETE` | `/v1/clients/{uid}` | 顧客の削除(論理削除) | `write:clients` | | `POST` | `/v1/clients/{uid}/embed_tokens` | 埋め込み URL の発行 | `embed` | | `GET` | `/v1/clients/{uid}/examinations` | 顧客の診断一覧 | `read:examinations` | | `GET` | `/v1/examinations` | 診断一覧(企業横断) | `read:examinations` | | `POST` | `/v1/examinations` | ヘッドレス新規分析(写真 2 枚を送って分析を依頼) | `write:examinations` | | `GET` | `/v1/examinations/{uid}` | 診断詳細 | `read:examinations` | | `PATCH` | `/v1/examinations/{uid}` | 診断の更新(日付のみ) | `write:examinations` | | `DELETE` | `/v1/examinations/{uid}` | 診断の削除(論理削除) | `write:examinations` | | `GET` | `/v1/company` | 企業情報 | `read:settings` | | `PATCH` | `/v1/company` | 企業設定の更新 | `write:settings` | | `GET` | `/v1/shops` | 店舗一覧 | `read:settings` | | `GET` | `/v1/shops/{uid}` | 店舗詳細 | `read:settings` | | `PATCH` | `/v1/shops/{uid}` | 店舗設定の更新 | `write:settings` | | `GET` | `/v1/staffs` | スタッフ一覧 | `read:settings` | | `GET` | `/v1/threshold_levels` | 判定レベルのマスタ | `read:settings` | | `GET` | `/v1/reports/examinations` | 診断数の集計 | `read:reports` | | `GET` | `/v1/reports/scores` | スコアの集計 | `read:reports` | | `GET` | `/v1/reports/clients` | 顧客の集計 | `read:reports` | | `GET` | `/v1/reports/usage` | 今月の利用状況 | `read:reports` | 項目の詳細・レスポンスの形は [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) が正本です。 ## 一覧のページングと差分同期 ``` GET /v1/clients?limit=50 → { "data": [...], "next_cursor": "MTc2MTYxMjAwMDAwMDAwMDo0Mg==" } GET /v1/clients?limit=50&cursor=MTc2MTYxMjAwMDAwMDAwMDo0Mg== → { "data": [...], "next_cursor": null } ← null なら最後 ``` - `limit` は 1〜100(既定 20)。並びは更新の新しい順(`updated_at` 降順) - `next_cursor` はそのまま次のリクエストに渡してください(中身に意味はありません) - 差分同期には `updated_since`(ISO 8601)を使います - 店舗・スタッフ・判定レベルは全件を返します(`next_cursor` は常に null) ## 書き込みの作法(冪等キー・楽観ロック) | 操作 | 作法 | |---|---| | 作成(`POST`) | `Idempotency-Key` ヘッダー(UUID 推奨・最大 255 文字・24 時間保持)。同じキー・同じ本文の再送には最初の応答をそのまま返します(`Idempotent-Replayed: true`)。写真を送る `POST /v1/examinations` では必須 | | 更新(`PATCH`) | **`If-Match` 必須**。直前の `GET`(または `PATCH`)で受け取った `ETag` をそのまま付けます。ほかで先に更新されていたら `412 precondition_failed` になるので、`GET` し直してからやり直します | | 削除(`DELETE`) | 論理削除。`204 No Content` | ```bash # GET で ETag を取り、If-Match に付けて更新する ETAG=$(curl -s -D - -o /dev/null "$BASE/v1/clients/CL12345678" -H "Authorization: Bearer $SNV_KEY" \ | awk 'tolower($1)=="etag:" {print $2}' | tr -d '\r') curl -s -X PATCH "$BASE/v1/clients/CL12345678" \ -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \ -H "If-Match: $ETAG" \ -d '{"phone_number":"09011112222"}' ``` - 本文は渡した項目だけを変えます(`null` を渡すとその項目を空にします) - 詳細(`/v1/clients/{uid}` など)は強い `ETag` を返します。`If-None-Match` に付けて送ると、変わっていなければ `304 Not Modified` になります - 同じ `Idempotency-Key` の操作が処理中、または前回がサーバーエラーで結果が分からないときは `409 operation_in_progress`(24 時間は同じキーを使えません。結果を `GET` で確かめてください)。`409`・`429` の応答は保存しないので、時間をおいて同じキーで再送すれば再実行されます - 同じ `Idempotency-Key` を別の内容に使うと `422 idempotency_key_reused`、`PATCH` に `If-Match` が無いと `428 precondition_required` ## 写真を送って分析する(`POST /v1/examinations`) 正面・側面の写真を multipart で送ると、画面で撮影したときと同じ診断ができます。 | 項目 | 内容 | |---|---| | `client_uid` | 必須。対象の顧客 | | `images[standing]` / `images[standing_side]` | 必須。正面・側面の写真 | | `shop_uid` | 省略時は顧客の店舗 | | `date` / `analysis_purpose` / `threshold_level_id` | 任意。判定レベルは受付時点で固定されます | | `enable_ai_advice` | 既定 true。企業の設定が OFF なら `ai_advice: disabled`、AI アドバイスの残数が 0 なら AI なしで受け付けて `ai_advice: skipped_no_stock` | | `notify_client` | 既定 false。true なら完了時に顧客へ LINE / メールで知らせます | | `webhook_url` | 任意。この分析だけの通知先(省略時はキーに設定した URL) | ### 分析に使う写真 - **JPEG または PNG、1枚 10MB 以下**。正面と側面の2枚 - 全身が写り、画面で撮影するときと同じ構図の写真を使ってください - 分析は、撮影画面と同じ **3:4(480×640)の枠** に写真を収めて行います。縦長・横長の写真は上下または左右に黒帯が入ります(元の写真の解像度は保持されません)。結果の `image_url`(骨格線入り)・`shot_image_url`(骨格線なし)はこの枠の画像です - ゆったりした服装や暗い照明では結果が変わります。体のラインが分かる服装・明るい場所での撮影をおすすめします ### 進み方と制限 - `analysis_status` は `pending` → `processing` → `completed` | `failed`。`analysis_checkpoint` に完了した工程(`predict_front` / `predict_side` / `render` / `analyze` / `score` / `ai_advice` / `done`)、失敗時は `analysis_error_stage` に失敗した工程が入ります - 受付時に **店舗の月間分析回数** と **企業の AI アドバイス残数** を予約します。分析が失敗・削除されても戻りません(画面で撮影したときと同じ扱いです) - 同時に処理できる API からの分析は企業ごとに 5 件までです。超えると `429 too_many_pending_analyses`(完了を待って、**同じ `Idempotency-Key` で再送**してかまいません) - 骨格検出の一時的な失敗は 3 回まで自動で再試行します。30 分以上 `processing` のまま止まった分析は自動で積み直します - 受け付けたあとにキーを失効しても分析は完了します(Webhook は送りません) | status | type の末尾 | いつ | |---|---|---| | 400 | `idempotency_key_required` | `Idempotency-Key` が無い | | 403 | `plan_inactive` | 契約・プランの状態により診断を作れない | | 404 | `not_found` | 顧客が無い・担当外 | | 422 | `validation_error` | 写真が無い・JPEG / PNG でない・10MB 超、`webhook_url` が不正、担当外の `shop_uid` など(`errors[].field`) | | 429 | `too_many_pending_analyses` | 処理中の分析が 5 件 | | 429 | `monthly_limit_exceeded` | 店舗の月間分析回数の上限(本文に `limit` / `current`) | | 429 | `rate_limited` | 流量超過(`Retry-After`) | ## Webhook(分析の完了・失敗を受け取る) API キーごとに **送信先 URL** を設定すると(`POST /v1/examinations` の `webhook_url` でも指定できます)、写真を送って依頼した分析が完了・失敗したときに、その URL へ POST します。画面で撮影した診断は対象外です。 ### ペイロード ```json { "id": "3f2b8c1e-5d7a-4a63-9b0e-2c4d6f8a1b2c", "type": "examination.completed", "created_at": "2026-10-29T03:00:00Z", "data": { "examination": { "uid": "EM12345678", "analysis_status": "completed", "...": "GET /v1/examinations の1件と同じ形" } } } ``` - `type` は `examination.completed` か `examination.failed` - `data.examination` は診断の一覧の1件と同じ形で、AI アドバイスの状態・本文は含みません。本文は `GET /v1/examinations/{uid}` で取得してください - イベントは1診断につき1件ですが、**配送は重複することがあります**(再送・受信後の切断など)。`id` で重複を除いてください - `data.examination.top_image_url` は短時間で切れる署名付き URL です。画像が必要なときは `GET /v1/examinations/{uid}` で取り直してください ### ヘッダーと署名の検証 | ヘッダー | 中身 | |---|---| | `X-Shiseinavi-Event-Id` | イベント ID(本文の `id` と同じ)。**受信側はこれで重複を除いてください** | | `X-Shiseinavi-Timestamp` | 送信時刻(epoch 秒) | | `X-Shiseinavi-Signature` | `v1=.<本文>") の hex>` | 署名シークレットはキーの発行時に1度だけ表示されます(画面の「署名シークレットを再発行」で取り直せます。古いシークレットはすぐ無効になります)。時刻が現在から 5 分以上ずれていれば捨てることをおすすめします(リプレイ対策)。 Node.js: ```js const crypto = require("crypto"); function verify(rawBody, headers, secret) { const timestamp = headers["x-shiseinavi-timestamp"]; const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"); const given = headers["x-shiseinavi-signature"] || ""; return expected.length === given.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given)) && Math.abs(Date.now() / 1000 - Number(timestamp)) < 300; } ``` Ruby(Rails): ```ruby secret = ENV["SHISEINAVI_WEBHOOK_SECRET"] timestamp = request.headers["X-Shiseinavi-Timestamp"] body = request.raw_post expected = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{body}") valid = ActiveSupport::SecurityUtils.secure_compare(expected, request.headers["X-Shiseinavi-Signature"].to_s) && (Time.now.to_i - timestamp.to_i).abs < 300 ``` 署名は**受け取った本文のバイト列そのまま**で計算します(JSON を読み直してから並べ直すと一致しません)。 ### 送信先の条件と再送 - 送信先は **https・ポート 443・公開アドレス** のみです(プライベート・ループバック・リンクローカル・クラウドのメタデータ宛ては、登録時と送信時の両方で拒否します)。リダイレクトは追いません - **2xx を 10 秒以内に返してください**。応答本文は 64KB までにしてください - 2xx 以外・タイムアウトは失敗として、1 分・10 分・1 時間・6 時間・24 時間後に再送します(最初の送信と合わせて計 6 回)。それでも失敗した配送は、管理画面の「Webhook の配送履歴」に残ります - 署名シークレットが無いキー(Webhook の公開前に発行したキー)には送信しません。シークレットを再発行してください ## 埋め込み URL(撮影画面・結果画面を自社アプリから開く) `POST /v1/clients/{uid}/embed_tokens`(スコープ `embed`)で、その顧客の画面に **30 分・1 回限り** でログインできる URL を発行します。 | `kind` | 開く画面 | できること | |---|---|---| | `scan` | 診断画面(撮影方法の選択から) | 撮影して診断を作る(顧客情報の更新・比較の作成はできません) | | `mypage` | 顧客のマイページ | 閲覧のみ | | `result` | 指定した診断の結果(`examination_uid` が必須) | 閲覧のみ | - ログイン後の画面は 30 分有効です。キーの失効・発行したスタッフの停止・顧客が担当外の店舗に移ったときは、その時点で使えなくなります - 開き方は **新しいタブかリダイレクト** をおすすめします(iframe での表示は、カメラの権限・Cookie の扱いを検証中です) ## エラー エラーは [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) の `application/problem+json` で返します。 ```json { "type": "https://posture-api.saucer-saas.com/problems/validation_error", "title": "Unprocessable Entity", "status": 422, "detail": "パラメータに誤りがあります", "errors": [{ "field": "from", "code": "period_too_long", "message": "期間は最大 13 か月です。期間を短くしてください" }] } ``` `type` はエラーの種類を表す識別子です。**末尾(`validation_error` など)で種類を見分けてください**(URL として開く必要はありません)。 | status | type の末尾 | いつ | |---|---|---| | 401 | `unauthorized` | キーが無い・不正・失効・期限切れ・API が無効・発行者が停止(理由は区別しません) | | 403 | `insufficient_scope` / `plan_inactive` | スコープ不足 / 契約・プランの状態により診断を作れない | | 404 | `not_found` | 存在しない・他社・担当外の店舗のデータ | | 409 | `conflict` / `operation_in_progress` | `external_id` の重複 / 同じ `Idempotency-Key` の操作が処理中・結果不明 | | 412 | `precondition_failed` | `If-Match` が今の内容と違う | | 422 | `validation_error` / `idempotency_key_reused` | パラメータ不正(`errors[].field` / `code` / `message`) / 冪等キーの使い回し | | 428 | `precondition_required` | `PATCH` に `If-Match` が無い | | 429 | `rate_limited` / `too_many_pending_analyses` / `monthly_limit_exceeded` | 流量超過(`Retry-After` 秒後に再試行) / 分析の同時実行数・月間上限 | | 503 | `maintenance` | メンテナンス中(読み取りも止まります) | | 500 | `internal_error` | サーバーエラー | ## 流量制限 | 対象 | 上限 | |---|---| | キーごと | 120 回/分・5,000 回/日 | | 企業ごと(全キーの合計) | 600 回/分 | | 集計(`/v1/reports/*`) | 上とは別に、キーごと 30 回/分 | | 写真の分析の受付(`POST /v1/examinations`) | 上とは別に、キーごと 10 回/分 | | 認証前(IP ごと) | 300 回/分 | | 認証失敗 | IP ごと 20 回/分(超えると 1 分間すべて 429) | 超えると `429` と `Retry-After`(秒)を返します。 ## 集計 API - `GET /v1/reports/examinations`(診断数)・`/scores`(スコア)・`/clients`(顧客)・`/usage`(今月の利用状況)。スコープ `read:reports` - 期間は `from` / `to`(診断日、両端を含む)。省略時は今日までの 30 日間で、最大 13 か月です。`granularity` は `day` / `week`(月曜始まり)/ `month` - `/v1/reports/scores` は分析が完了した診断が対象で、判定基準の版 × 判定レベルごとに `groups` で返します(版・レベルが違う点数は混ぜて平均しません) - `/v1/reports/usage` で、店舗ごとの今月の診断数・上限・残りを返します ## 返さない情報 外部(特に AI)に渡ったときの指示の混入や漏えいを避けるため、次の情報は API で返しません: 顧客・診断のメモ/社内メモ、トークガイド、AI へのプロンプト、LINE の秘密情報、決済のキー、スタッフのメールアドレス。 ## AI エージェントから使う 姿勢ナビの API は通常の REST API なので、HTTP を呼べる AI エージェントからそのまま使えます。専用の連携機能を入れる必要はありません。 - **Claude Code など、手元でコマンドを実行できるエージェント**: このページの URL と [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) を渡し、API キーは環境変数(例: `SNV_KEY`)に入れて「環境変数のキーを使って」と伝えます。curl やスクリプトで、写真の送信(multipart)まで実行できます - **ChatGPT のカスタムアクション(GPTs の Actions)など、OpenAPI を読み込めるツール**: [OpenAPI(YAML)](https://shiseinavi.com/openapi/company-api.yaml) を読み込ませ、認証に API キー(Bearer)を設定します。写真のアップロード(multipart)に対応しているかは、お使いのツールによります 安全に使うために: - **AI 用に専用のキーを発行し、スコープを必要なものだけに絞ってください**(読むだけなら `read:*` のみ)。使い終わったら失効します - キーをチャットの本文やコードに直接書かないでください。環境変数・ツールの認証設定に入れます - 書き込み(登録・更新・削除・分析の依頼)は、実行前に内容を確認させる運用をおすすめします - 顧客の氏名・写真・姿勢データが外部の AI サービスに送られる場合があります。各 AI サービスのデータの扱いと、自社のプライバシーポリシー・お客様の同意の範囲でご利用ください AI アシスタントに使い方を聞くときのプロンプト例: ```text 姿勢ナビの API で顧客を登録して写真を分析し結果を取得する手順を教えて。ドキュメント: https://shiseinavi.com/docs/api と https://shiseinavi.com/llms.txt ``` ## よくある質問 ### API は誰が使えますか 姿勢ナビを契約している店舗(企業)が、管理画面で API キーを発行して使えます。キーを発行できるのは企業管理者(オーナーを含む)です。 ### 写真を送ってから結果が出るまで、どれくらいかかりますか 20〜60 秒ほどです(骨格検出2回と AI アドバイスの生成を含みます)。`GET /v1/examinations/{uid}` を 5 秒間隔程度でポーリングするか、Webhook で完了の通知を受け取ってください。 ### API で分析した診断は、店舗の画面にも出ますか 出ます。画面で撮影した診断と同じく、顧客の診断履歴・結果画面・手渡し PDF にそのまま載ります。 ### 分析の回数は、画面での撮影と別に数えますか 同じです。API で受け付けた分析も、店舗の月間分析回数と企業の AI アドバイス残数を使います。分析が失敗・削除されても戻りません。 ### 撮影画面を自社アプリに組み込めますか `POST /v1/clients/{uid}/embed_tokens` で、診断画面(`scan`)・マイページ(`mypage`)・結果画面(`result`)を開く URL(30 分・1 回限り)を発行できます。新しいタブかリダイレクトで開いてください。 ### API はいつまで β 版ですか 未定です。β版です。予告なく仕様を変更する場合があります。 仕様の変更はこのページと OpenAPI に反映します。API についてのご相談は「[無料お問い合わせ](https://shiseinavi.com/contact)」からどうぞ。 --- # 姿勢分析 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円〜。 --- # 写真からの姿勢分析を、自社のアプリやシステムに組み込むには? 姿勢ナビの API(β)では、2つの方法で姿勢分析を自社のアプリやシステムに組み込めます。自社のアプリで撮った正面・側面の写真を API に送ると、サーバーで分析して結果を JSON で返します。撮影から姿勢ナビの画面を使いたい場合は、撮影画面・結果画面を開く URL(30 分・1 回限り)を API で発行し、新しいタブかリダイレクトで開きます。 URL: https://shiseinavi.com/guides/embed-posture-analysis-in-app 更新日: 2026-10-29 ## 2つの方法の違い | | 方法A: 写真を API で送る | 方法B: 姿勢ナビの画面を開く(埋め込み URL) | |---|---|---| | 撮影 | 自社アプリで撮る | 姿勢ナビの撮影画面で撮る | | 結果の見せ方 | JSON を受け取り、自社の画面で表示する | 姿勢ナビの結果画面をそのまま開く | | 使う API | `POST /v1/examinations`(`write:examinations`) | `POST /v1/clients/{uid}/embed_tokens`(`embed`) | | 向いている場合 | 自社アプリの中で体験を完結させたい | 撮影のガイドや結果画面を作らずに使いたい | どちらの方法でも、診断は店舗の画面の診断履歴・結果画面・手渡し PDF に同じように残ります。 ## 共通: 顧客をそろえる 自社システムの顧客 ID を `external_id` に入れて登録しておくと、あとから ID で引けます。 ```bash KEY=$(uuidgen) # この依頼の冪等キー(再送でも同じ値を使う) curl -s -X POST "https://posture-api.shiseinavi.com/v1/clients" \ -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: $KEY" \ -d '{"name":"山田太郎","external_id":"CRM-12345"}' curl -s "https://posture-api.shiseinavi.com/v1/clients?external_id=CRM-12345" -H "Authorization: Bearer $SNV_KEY" ``` 通信が切れたときは、同じ `KEY` で同じコマンドをもう一度実行してください。新しい登録・診断は作られず、同じ応答が返ります(`KEY` は依頼1回ごとに1度だけ作り、再送では作り直さない)。 ## 方法A: 写真を送って結果を受け取る ```bash KEY=$(uuidgen) # この依頼の冪等キー(再送でも同じ値を使う) curl -s -X POST "https://posture-api.shiseinavi.com/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度だけ作り、再送では作り直さない)。 - 写真は JPEG / PNG、1枚 10MB 以下。全身が写り、撮影画面と同じ構図のものを使います - 撮影画面と同じ 3:4(480×640)の枠に収めて分析します。縦長・横長の写真には黒帯が入ります - 20〜60 秒ほどで `analysis_status` が `completed` になります。ポーリング(5 秒間隔程度)か [Webhook](https://shiseinavi.com/guides/receive-analysis-webhook) で受け取ります - `notify_client: true` を付けると、完了時に顧客へ LINE / メールで知らせます ## 方法B: 撮影画面・結果画面を開く URL を発行する ```bash curl -s -X POST "https://posture-api.shiseinavi.com/v1/clients/CL12345678/embed_tokens" \ -H "Authorization: Bearer $SNV_KEY" -H "Content-Type: application/json" \ -d '{"kind":"scan"}' ``` | `kind` | 開く画面 | |---|---| | `scan` | 診断画面(撮影方法の選択から)。撮影して診断を作れます | | `mypage` | 顧客のマイページ(閲覧のみ) | | `result` | 指定した診断の結果(`examination_uid` が必須。閲覧のみ) | - URL は **30 分・1 回限り** です。開いたあとの画面も 30 分有効です - 開き方は新しいタブかリダイレクトをおすすめします(iframe での表示はカメラの権限・Cookie の扱いを検証中です) ## 関連 - [API ドキュメント(β): 写真を送って分析する](https://shiseinavi.com/docs/api#analysis) - [API ドキュメント(β): 埋め込み URL](https://shiseinavi.com/docs/api#embed) - [姿勢分析 API(β)はどう使い始めればいいですか?](https://shiseinavi.com/guides/posture-analysis-api-quickstart) --- 姿勢ナビ(運営: 株式会社Saucer)は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。 --- # 姿勢分析の完了を Webhook で受け取るには? 姿勢ナビの API(β)では、API キーごとに Webhook の送信先 URL を設定すると、写真を送って依頼した分析が完了・失敗したときに、その URL へ署名付きで POST します。受信側は X-Shiseinavi-Signature を署名シークレットで検証し、X-Shiseinavi-Event-Id で重複を除いて、10 秒以内に 2xx を返します。失敗した配送は 24 時間後まで段階的に再送されます。 URL: https://shiseinavi.com/guides/receive-analysis-webhook 更新日: 2026-10-29 ## 送信先を設定する - 管理画面の右上のメニューの「API設定 β」で、キーごとに **Webhook の送信先 URL** を設定します(キーの発行時にも入れられます)。分析ごとに変えたいときは、`POST /v1/examinations` の `webhook_url` で指定できます - 送信先は **https・ポート 443・公開アドレス** のみです。リダイレクトは追いません - 署名シークレットは発行時に1度だけ表示されます。なくしたときは「署名シークレットを再発行」で取り直します(古いシークレットはすぐ無効になります) - 通知の対象は、API で写真を送って依頼した分析だけです(画面で撮影した診断は対象外) ## 届くもの ```json { "id": "3f2b8c1e-5d7a-4a63-9b0e-2c4d6f8a1b2c", "type": "examination.completed", "created_at": "2026-10-29T03:00:00Z", "data": { "examination": { "uid": "EM12345678", "analysis_status": "completed" } } } ``` | ヘッダー | 中身 | |---|---| | `X-Shiseinavi-Event-Id` | イベント ID(本文の `id` と同じ) | | `X-Shiseinavi-Timestamp` | 送信時刻(epoch 秒) | | `X-Shiseinavi-Signature` | `v1=` | `type` は `examination.completed`(完了)か `examination.failed`(失敗)です。`data.examination` は `GET /v1/examinations` の1件と同じ形です。 ## 署名を検証する(Node.js) ```js const crypto = require("crypto"); function verify(rawBody, headers, secret) { const timestamp = headers["x-shiseinavi-timestamp"]; const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"); const given = headers["x-shiseinavi-signature"] || ""; return expected.length === given.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given)) && Math.abs(Date.now() / 1000 - Number(timestamp)) < 300; } ``` - 署名は**受け取った本文のバイト列そのまま**で計算します(JSON を読み直して並べ直すと一致しません) - 時刻が 5 分以上ずれているものは捨てることをおすすめします(リプレイ対策) ## 応答と再送 - **10 秒以内に 2xx** を返してください。重い処理(画像の取得など)は自社のキューに回します - 2xx 以外・タイムアウトは失敗として、1 分・10 分・1 時間・6 時間・24 時間後に再送します(計 6 回)。それでも失敗した配送は、管理画面の「Webhook の配送履歴」に残ります - 再送で同じイベントが2回届くことがあります。`X-Shiseinavi-Event-Id` で重複を除いてください - `data.examination.top_image_url` は短時間で切れる URL です。画像は `GET /v1/examinations/{uid}` で取り直してください ## 関連 - [API ドキュメント(β): Webhook](https://shiseinavi.com/docs/api#webhook) - [写真からの姿勢分析を、自社のアプリやシステムに組み込むには?](https://shiseinavi.com/guides/embed-posture-analysis-in-app) --- 姿勢ナビ(運営: 株式会社Saucer)は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。 --- # AI エージェント(Claude Code・ChatGPT など)から姿勢ナビを操作するには? 姿勢ナビの API(β)は通常の REST API で、仕様を OpenAPI(YAML)で公開しているので、HTTP を呼べる AI エージェントからそのまま使えます。Claude Code のように手元でコマンドを実行できるエージェントには、ドキュメントの URL を渡し、API キーを環境変数に入れて頼みます。ChatGPT のカスタムアクションなど OpenAPI を読み込めるツールには、OpenAPI を読み込ませて API キー(Bearer)を設定します。 URL: https://shiseinavi.com/guides/use-from-ai-agent 更新日: 2026-10-29 ## 何ができるか AI エージェントから、API でできることをそのまま頼めます。 - 顧客を探す・登録する・更新する(例:「外部 ID が CRM-12345 の顧客の、最近の診断を一覧にして」) - 正面・側面の写真を送って分析し、結果を読む(例:「この2枚の写真で山田さんの姿勢を分析して、結果を要約して」) - 集計を読む(例:「今年の月ごとの診断数を店舗別に表にして」) - 撮影画面・結果画面を開く URL を発行する 専用の連携機能を入れる必要はありません。 ## Claude Code など、手元でコマンドを実行できるエージェント 1. 管理画面の「API設定 β」で AI 用のキーを発行し、ターミナルで環境変数に入れます ```bash export SNV_KEY="snv_xxxxxxxx_..." ``` 2. ドキュメントを渡して頼みます ```text 姿勢ナビの API で顧客を登録して写真を分析し結果を取得する手順を教えて。ドキュメント: https://shiseinavi.com/docs/api と https://shiseinavi.com/llms.txt API キーは環境変数 SNV_KEY に入っています。書き込みの前に、送る内容を見せて確認してください。 ``` curl やスクリプトを実行できるので、写真の送信(multipart)まで任せられます。 ## ChatGPT のカスタムアクションなど、OpenAPI を読み込めるツール 1. [OpenAPI(YAML)](https://shiseinavi.com/openapi/company-api.yaml) の URL か中身を、アクションのスキーマとして読み込ませます 2. 認証に API キー(Bearer)を設定します 3. 必要なエンドポイントだけを残すと、AI が迷いにくくなります(例: 顧客の検索と診断の取得だけ) 写真のアップロード(multipart)に対応しているかは、お使いのツールによります。対応していない場合は、読み取り・顧客の登録などの JSON の操作に使い、写真の送信は自社のシステムから行ってください。 ## 安全に使うために - **AI 用に専用のキー**を発行し、スコープを必要なものだけに絞ります(読むだけなら `read:clients`・`read:examinations` など) - 有効期限を短めにし、使い終わったら「失効する」で止めます。直近の呼び出し(50件)は管理画面で確認できます - キーをチャットの本文・コード・共有ドキュメントに書かないでください - 顧客の氏名・写真・姿勢データが外部の AI サービスに送られる場合があります。各 AI サービスのデータの扱いと、自社のプライバシーポリシー・お客様の同意の範囲でご利用ください - API は、顧客・診断のメモ、トークガイド、AI へのプロンプト、スタッフのメールアドレスなどを返しません(AI に渡ったときの指示の混入や漏えいを避けるため) - β版です。予告なく仕様を変更する場合があります。 エージェントに渡すドキュメントは、最新の [llms-full.txt](https://shiseinavi.com/llms-full.txt) か [OpenAPI](https://shiseinavi.com/openapi/company-api.yaml) を使ってください ## 関連 - [API ドキュメント(β)](https://shiseinavi.com/docs/api) - [llms.txt(AI 向けの案内)](https://shiseinavi.com/llms.txt) - [姿勢分析 API(β)はどう使い始めればいいですか?](https://shiseinavi.com/guides/posture-analysis-api-quickstart) --- 姿勢ナビ(運営: 株式会社Saucer)は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。