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

# ✨ TokenLab API 統合スキル

> 管理中の TokenLab API 統合スキルをインストールし、coding agent がモデルを発見し、対応状況を読み、API エラーから回復できるようにします。

<Note>
  このページは、管理中の共有 `tokenlab-api-integration` スキルを説明します。正規の配布元は [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills) で、公開リポジトリには意図的にこのスキルだけを残しています。
</Note>

<Note>
  このページはスキルのインストールと agent ワークフロー向けです。エンドポイント、SDK、クライアント設定は各ツールの専用統合ページまたは API Reference を参照してください。
</Note>

## このスキルでできること

* TokenLab のチャット、画像、音声、動画、翻訳などの API ファミリー向けに、最小の実行可能サンプルを生成します。
* OpenAI 互換クライアントでは `https://api.tokenlab.sh/v1` を使い、Anthropic や Gemini のネイティブルートに切り替えるべき場面を説明します。
* 古いリストを推測するのではなく、`/v1/models`、`/llms.txt`、`recommended_for` の候補一覧でモデルを発見します。
* 非チャットリクエストを再試行する前にモデルの対応状況を読み、不対応フィールドを静かに捨てないようにします。
* `did_you_mean`、`suggestions`、`retry_after`、`recommended_request` などの Agent-First エラーヒントを扱います。

## インストール

<Note>
  正規の非対話インストールコマンドを使います：

  ```bash theme={null}
  npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
  ```

  TokenLab skills リポジトリから共有 `tokenlab-api-integration` スキルをインストールします。

  ツールが installer に対応していない場合は、リポジトリの `skills/tokenlab-api-integration/` をツールの共有 skills または rules ディレクトリへコピーしてください。
</Note>

### 既存インストールの更新

TokenLab skills リポジトリ整理前にインストールした場合は、同じコマンドを再実行してください。現在の公開パッケージは小さく、生成されたローカル検索スクリプトに依存しません。

### インストール確認

coding agent に聞きます：

```
利用できる skills は何ですか？
```

`tokenlab-api-integration` が見えればインストール成功です。

## API Key の取得

<Steps>
  <Step title="TokenLab にアクセス">
    [tokenlab.sh](https://tokenlab.sh) を開きます
  </Step>

  <Step title="サインイン">
    アカウントを作成するかログインします
  </Step>

  <Step title="API Key を取得">
    [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) を開いて新しい key を作成します
  </Step>

  <Step title="key をコピー">
    key は `sk-...` で始まります。安全に保存してください。
  </Step>
</Steps>

<Tip>
  API key をプロンプトやソースコードに貼り付けないでください。スキルは使用する環境変数を確認し、その変数から key を読むコードを生成します。
</Tip>

## 推奨 Agent ワークフロー

1. ユーザーが求める言語と API ファミリーに合う、最小の動作例から始めます。
2. モデル選択が未確定なら、ハードコードする前に `/v1/models` または `https://api.tokenlab.sh/llms.txt` を呼びます。
3. 非チャット作業では `/v1/models?recommended_for=<scene>` を呼びます。`<scene>` は `image`、`video`、`music`、`3d`、`tts`、`stt`、`embedding`、`rerank`、`translation` のいずれかです。
4. 失敗した非チャットリクエストを変更する前に `/v1/models/:model` を読み、`supported_operations`、`supported_parameters`、`request_endpoint`, `request_endpoint_by_operation`、`request_shape_mode`、`recommended_request` に合わせます。
5. API が Agent-First エラーを返したら構造化フィールドでリクエストを修正し、`retryable` のときだけ再試行します。

## 最小チャット例

この例は OpenAI Python SDK と TokenLab base URL を使います：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
```

実行方法：

```bash theme={null}
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py
```

## モデル発見と対応状況

古い同梱リストよりライブ発見を優先します：

```bash theme={null}
# 機械可読 API 概要
curl https://api.tokenlab.sh/llms.txt

# モデル一覧
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# 非チャット向けランキング候補
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# 非チャットリクエストを再試行する前に単一モデルの対応状況を読む
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# 価格だけの詳細
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"
```

## ネイティブルーティングのヒント

通常のチャット、Responses、画像、embedding、音声、rerank の例では OpenAI 互換の `/v1` が既定です。プロバイダー固有の動作が必要な場合、または TokenLab が最適化ヒントとして `X-TokenLab-Native-Endpoint` を返す場合だけ、Anthropic または Gemini のネイティブルートを使います。

```
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
```

## Agent-First エラー回復

エラーには coding agent が直接解析できるフィールドが含まれます：

| エラー              | 有用なフィールド                                                                                                                                         | Agent の対応                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
| モデル名が間違っています     | `did_you_mean`, `suggestions`, `hint`                                                                                                            | 修正後のモデルまたは推奨代替モデルで再試行します                                |
| 残高不足             | `balance_usd`, `estimated_cost_usd`, `suggestions`                                                                                               | 承認を求めるか、利用可能なモデルに切り替えます                                 |
| レート制限または一時的な利用不可 | `retryable`, `retry_after`, `alternatives`                                                                                                       | 待機して再試行するか、表示された代替モデルを選びます                              |
| 非チャット契約の不一致      | `supported_operations`, `supported_parameters`, `request_endpoint`, `request_endpoint_by_operation`, `request_shape_mode`, `recommended_request` | 対応状況からリクエストを作り直し、意図を変えるフィールドは return a clear error にします |

## 対応 API ファミリー

| ファミリー                 | 主なパス                                                                     |
| --------------------- | ------------------------------------------------------------------------ |
| Chat と Responses      | `/v1/chat/completions`, `/v1/responses`                                  |
| Claude ネイティブ messages | `/v1/messages`                                                           |
| Gemini ネイティブリクエスト     | `/v1beta/models/{model}:generateContent`                                 |
| 画像                    | `/v1/images/generations`, `/v1/images/edits`                             |
| 動画                    | `/v1/videos/generations`                                                 |
| 音楽                    | `/v1/music/generations`                                                  |
| Worlds                | `/v1/worlds/generations` と world 状態・メディアアセット endpoint                    |
| 3D                    | `/v1/3d/generations`                                                     |
| 音声                    | `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations` |
| Realtime              | `/v1/realtime?model={model}`                                             |
| Embeddings と rerank   | `/v1/embeddings`, `/v1/rerank`                                           |
| テキスト翻訳                | `/v1/translations`                                                       |

## ベストプラクティス

<CardGroup cols={2}>
  <Card title="API Key の安全性" icon="shield">
    環境変数とサーバー側呼び出しを使い、フロントエンドコードで key を公開しないでください。
  </Card>

  <Card title="非チャットは契約優先" icon="file-code">
    画像、動画、音楽、3D、翻訳、音声、embedding、rerank を再試行する前に `/v1/models?recommended_for=...` と `/v1/models/:model` を読みます。
  </Card>

  <Card title="最小の実行可能例" icon="terminal">
    抽象化、キュー、UI フローを追加する前に、まず 1 つの動く呼び出しを作ります。
  </Card>

  <Card title="構造化ヒントを使う" icon="rotate-cw">
    コードを変更する前に `did_you_mean`、`retry_after`、`alternatives`、`recommended_request` を解析します。
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="スキルが自動で発火しませんか？">
    リクエスト内で “TokenLab” または “TokenLab API” に触れてください。例：`TokenLab を使って Node.js アプリに画像生成を追加して`。
  </Accordion>

  <Accordion title="どの coding agent に対応していますか？">
    共有 skill または rules ディレクトリに対応する任意の coding agent で使えます。`skills` installer は対応 agent を自動で処理します。
  </Accordion>

  <Accordion title="スキルを更新するには？">
    インストールコマンドを再実行してください。正規の公開リポジトリからローカルコピーを更新します。

    ```bash theme={null}
    npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
    ```
  </Accordion>
</AccordionGroup>

## リソース

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/ja/guides/agent-first-api">
    構造化エラーヒントと回復動作
  </Card>

  <Card title="API ドキュメント" icon="book" href="https://docs.tokenlab.sh">
    エンドポイント別の設定と API Reference
  </Card>

  <Card title="モデル" icon="sparkles" href="https://tokenlab.sh/ja/models">
    利用可能なモデルを確認
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    agents 向けの機械可読 API 概要
  </Card>
</CardGroup>

<Info>
  質問がある場合は [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) または [support@tokenlab.sh](mailto:support@tokenlab.sh) まで。
</Info>