はじめに

環境設定

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

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

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

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

Pythonの例を使う場合

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

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

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

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

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

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

APIキーを取得する

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

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

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

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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

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

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

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

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

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

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

  • 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 フィールドを渡せば、サーバーが代わりにファイルを取得します。詳細はクイックスタートをご覧ください。
  • rate_limit_exceededが表示される場合： レート制限をご覧ください。制限はアカウントごとであり、リクエストタイプごとではありません。そのため、ポーリング呼び出しのバーストが、アップロードのバーストと同じ制限に達する可能性があります。
📮 contact email: [email protected]