> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lymo.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# クイックスタート

> 認証付きリクエストを最初に送るまで

本ガイドでは、ゼロから分析実行までの流れを、いくつかの `curl` コマンドで示します。

<Tip>
  REST を直接叩くより CLI が好みであれば、[`lymo`](/guides/cli) をインストールして `lymo setup && lymo summary latest` を実行してください。同じ API を、ブラウザ認証・名前付きプロファイル・MCP 連携込みで利用できます。
</Tip>

## 1. API キーを取得する

Lymo Web アプリで **設定 → Platform** を開き、**Create key** をクリックします。生成されたキー（`lymo_` で始まる）をコピーしてください。キーが表示されるのは作成時の一度だけです。

```bash theme={null}
export LYMO_KEY=lymo_xxxxxxxxxxxxxxxx
export LYMO_BASE=https://platform.lymo.jp
```

`LYMO_BASE` はホスト名だけにしてあります。これにより、バージョンなしの `/health` と、バージョン付きの `/v1/*` のどちらも同じ変数から組み立てられます。

## 2. 接続を確認する

まず認証不要のヘルスチェックで API への到達性を確認します。

```bash theme={null}
curl "$LYMO_BASE/health"
# → { "data": { "status": "ok" }, "meta": { "request_id": "req_..." } }
```

次にキーが受け付けられることを確認します。

```bash theme={null}
curl "$LYMO_BASE/v1/members/me" \
  -H "Authorization: Bearer $LYMO_KEY"
```

`/health` は成功するのに `/v1/members/me` が失敗する場合は、認証側の問題です（キーの誤り、失効、スコープ不足など）。`/health` 自体が失敗する場合は、ネットワークかベース URL の問題です。

## 3. 動画の一覧を取得する

```bash theme={null}
curl "$LYMO_BASE/v1/videos?limit=5" \
  -H "Authorization: Bearer $LYMO_KEY"
```

レスポンスから動画 ID を 1 件選んで保存します。ID は UUID であり、リソースごとのプレフィックスは付きません。

```bash theme={null}
export VIDEO=a1b2c3d4-5e6f-7890-abcd-ef0123456789
```

## 4. 分析を起動する

分析は非同期処理です。`POST` はリソースを作成してすぐに `201` と `status: "processing"` を返します。完了はポーリングまたは Webhook で取得してください。

```bash theme={null}
RESPONSE=$(curl -s -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY")

echo "$RESPONSE" | jq .
# {
#   "data": {
#     "id": "b2c3d4e5-...",
#     "status": "processing",
#     "video_id": "a1b2c3d4-...",
#     "started_at": null,
#     "finished_at": null,
#     "created_at": "2026-04-24T12:34:56.000Z",
#     "updated_at": "2026-04-24T12:34:56.000Z"
#   },
#   "meta": { "request_id": "req_..." }
# }

ANALYSIS=$(echo "$RESPONSE" | jq -r .data.id)
echo "Started analysis $ANALYSIS"
```

結果をポーリングします。

```bash theme={null}
curl "$LYMO_BASE/v1/videos/$VIDEO/analyses/$ANALYSIS" \
  -H "Authorization: Bearer $LYMO_KEY"
# → { "data": { "status": "processing" | "completed" | "failed", "result": {...}? }, "meta": {...} }
```

`status` が `completed` になると、同じリソース上に分析結果を含む `result` オブジェクトが追加されます。完全なポーリングループ、冪等性、Webhook への切り替え方は [非同期パターン](/guides/async-pattern) を参照してください。

## エラー処理

すべてのエラーは共通の形状を持ちます。セットアップ時に遭遇しやすいのは `unauthorized`（401）、`forbidden`（403）、`not_found`（404）、`validation_failed`（422）、`rate_limited`（429）です。コード一覧・推奨対応・クロステナント 404 の挙動など、完全なリファレンスは [エラー](/guides/errors) ガイドを参照してください。

## 冪等性

`POST` リクエストでは `Idempotency-Key` ヘッダーを受け付けます。ネットワーク再試行で重複処理が発生しうる場面（例: 分析作成 POST のタイムアウト直後の再送）では、必ず設定してください。

```bash theme={null}
curl -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 16)"
```

キャッシュの挙動、TTL、同じキーで新しいリクエストを強制する方法は、[非同期パターン → 冪等性](/guides/async-pattern#冪等性) に詳細があります。