# 環境設定 — APIキーとクライアントのインストール

> クライアントのインストール方法、ImageToTable.aiのAPIキーを安全に保存する方法、そしてv1 APIを呼び出す前に発生しがちな「リクエストを送ったらエラーが出た」問題をトラブルシューティングする方法を説明します。

このページは、ターミナルからHTTP APIを呼び出したことがない方向けです。 すでに`curl`や環境変数に慣れている方は、[クイックスタート](/developers/quickstart)に進んでください。

## クライアントをインストールする

カスタムヘッダー付きのHTTPリクエストを送信できるツールが必要です。よく使われる2つの選択肢を紹介します。

- **curl** — コマンドラインツールで、通常macOSとLinuxにはすでにインストールされています。ターミナルで `curl --version`と入力して確認してください。Windowsの場合は、 [curl.se/windows](https://curl.se/windows/)からインストールするか、 Git Bash / WSLにバンドルされているcurlを使用します。このドキュメントのすべての例は、最初にcurlコマンドで記述されています。
- **Postman**（またはInsomnia） — リクエストの作成と保存ができるグラフィカルアプリです。シェルコマンドを書くよりも フォームをクリックして操作したい場合に便利です。[postman.com/downloads](https://www.postman.com/downloads/) からインストールし、このサイトのcurlの例をURL、メソッド、ヘッダー、ボディを新しいリクエストにコピーして再現してください。

## Pythonの例を使う場合

このサイトのすべてのコードサンプルには、人気の[`requests`](https://requests.readthedocs.io/)ライブラリを使用したPythonタブがあります — **ImageToTable.aiの公式SDKではありません** （当社はSDKを公開していません。これらは標準的なクライアントを使ったプレーンなHTTP呼び出しです）。必要なものは次のとおりです。

- **Python 3.8以上** — `python3 --version`で確認してください。インストールされていない場合は [python.org/downloads](https://www.python.org/downloads/)から入手してください。
- **`requests`** — 標準ライブラリには含まれていないため、最初にインストールします。`pip install requests`（システムによっては`pip3 install requests`）。

ダウンロードしたファイル（xlsx/docx）を解析するエクスポートの例では、`openpyxl` / `python-docx`も使用します。 これらの特定の例を試す場合にのみ必要で、`pip install openpyxl python-docx`でインストールしてください。

## JavaScriptのサンプルコードについて

JavaScriptタブではネイティブの`fetch`APIを使用しています。ライブラリのインストールは不要ですが、ある程度新しいランタイムが必要です。

- **Node.js 20以上**（サーバーサイドで実行する場合） — `node --version`で確認してください。サンプルコードはトップレベルの`await`とグローバルの`crypto.randomUUID()`を使用しており、どちらも新しいNode.jsが必要です。Node 18（現在サポート終了）では、CommonJS/REPL以外で`crypto`がグローバルとして確実に利用できず、APIキーとは無関係に`crypto is not defined`という紛らわしいエラーで失敗する可能性があります。最新バージョンは[nodejs.org](https://nodejs.org/)から入手してください。
- または、**ブラウザのDevToolsコンソールにスニペットを貼り付ける**だけでも動作します。最新のブラウザはすべて同じAPI（`fetch`、`FormData`、`crypto.randomUUID()`）をネイティブにサポートしており、インストールは一切不要です。

## APIキーを取得する

APIキーはアカウントの[プロフィール設定ページ](/profile/)から発行されます。 v1 APIは有料プラン（Basic以上）で利用可能です。Freeプランのキーで呼び出すと、認証エラーではなく`plan_required`エラーが返ります。キー自体は有効ですが、v1の使用が許可されていないためです。

## APIキーを環境変数として保存する

共有、スクリーンショット、バージョン管理にコミットする可能性のあるコマンドにAPIキーを直接貼り付けないでください。代わりにシェルセッションにエクスポートし、すべてのリクエストで`$API_KEY`として参照してください。このサイトのすべてのサンプルコードは、この変数が存在することを前提としています。

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

この設定は現在のターミナルセッションでのみ有効です。永続的に設定するには、同じ行をシェルの起動ファイル（`~/.bashrc`、`~/.zshrc`など）に追加してください。スクリプトを作成する場合は、ソースコードにハードコードするのではなく、`.env`ファイルやシークレットマネージャーから読み込むようにしてください。

## テストリクエストを送信する

実際のドキュメントに進む前に、キーとセットアップが正しく動作していることを確認しましょう。

```bash
curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"
```

有料プランの有効なキーを使用すると、アカウントのスナップショット（プラン、ロール、利用可能なクレジット）が返されます。それ以外の場合は、以下のトラブルシューティングチェックリストを参照してください。

## トラブルシューティングチェックリスト

v1のエラーはすべて、`type`/`code`/`message`を含むJSONで返されます。完全なリストは[エラーハンドリング](/developers/guides/errors)ガイドをご覧ください。リクエストが機能しない場合の最初の確認ポイントは次のとおりです。

- **`missing_api_key`が表示される場合：** ヘッダーが正確に `Authorization: Bearer <key>` であるか確認してください。`Bearer`という単語、半角スペース1つ、その後にキーが続く必要があります。スペースの欠落や、`$API_KEY`内の余分な引用符が原因でこのエラーが発生します。
- **`invalid_api_key`が表示される場合：** キーがいずれのアカウントとも一致しないか、アカウントが無効になっています。プロフィールページからキーを再コピーしてください。キーは長いため、コピー＆ペースト時に切り詰められやすいです。
- **`plan_required`が表示される場合：** キーは有効ですが、アカウントがFreeプランです。v1を使用するには、Basicプラン以上にアップグレードしてください。
- **JSON応答ではなく接続エラーが表示される場合：** URLが `https://imagetotable.ai/api/v1/` で始まっていること、および必要なエンドポイントに対して `-X POST`（または適切なHTTPメソッド）を使用していることを再確認してください。POST専用エンドポイントへのGETリクエストはルートに到達しません。
- **ファイルをアップロードして予期しないエラーが表示される場合：** マルチパートファイルアップロードには、`-d`や生のJSONボディではなく、`-F "file=@/path/to/file.jpg"`（curlのフォームアップロードフラグ）を使用する必要があります。これらを混同することは、アップロードで最も一般的なミスです。先頭の `@` は、curlにそのパスを*自分のマシン上の*実際のファイルとして読み取るように指示します。これはURLではなく、コマンドを実行する前にそのファイルが存在している必要があります。手元にローカルファイルがない場合は、この手順を完全にスキップしてください。`file`の代わりに `url` フィールドを渡せば、サーバーが代わりにファイルを取得します。詳細は[クイックスタート](/developers/quickstart)をご覧ください。
- **`rate_limit_exceeded`が表示される場合：** [レート制限](/developers/guides/rate-limits)をご覧ください。制限はアカウントごとであり、リクエストタイプごとではありません。そのため、ポーリング呼び出しのバーストが、アップロードのバーストと同じ制限に達する可能性があります。

---

Source: https://imagetotable.ai/ja/developers/environment-setup