Studio API接続設定¶
YomiToku-Proには、YomiToku Studioとの接続に必要な認証、CORS、Request IDの仕組みが実装されています。
Studio APIは、Document Analyzer APIおよびTable Semantic Parser APIとは別のプロセスとして起動します。文書解析と帳票解析の両方を1つの接続先から利用できます。
| エンドポイント | 処理 |
|---|---|
GET /ping |
死活確認 |
GET /studio/v1/capabilities |
対応機能と制限値の取得 |
POST /studio/v1/document/analyze |
文書OCR・レイアウト解析 |
POST /studio/v1/form/analyze |
帳票・表解析（?mode=ocr_onlyで文字検出・認識のみ） |
POST /studio/v1/ocr/recognize-regions |
指定文字領域の部分再OCR（追加計上なし） |
POST /studio/v1/form/analyze-regions |
指定表領域のセル・構造再解析（追加計上なし） |
モデルと軽量モード¶
Studioサーバーは、Document Analyzer・Table Semantic Parserの各サーバーと同じモデル選択オプションで起動できます。指定は文書解析・帳票解析の両パイプラインに適用され、Text DetectorとText Recognizerは2つのパイプラインで共有されます。
# CPU向けの軽量モデルで起動（CPU環境では --lite は自動的に有効）
yomitoku_server studio --lite --host 127.0.0.1 --port 8000
# モデル名を明示して起動
yomitoku_server studio --tr_name parseqv4-large --td_name dbnetv2_1 --host 127.0.0.1 --port 8000
| オプション | 説明 |
|---|---|
-l, --lite |
軽量モデル（parseqv4-tiny 動的幅認識）で高速に推論。CPUでは検出もONNXで実行 |
--tr_name |
テキスト認識モデル名（例: parseqv4, parseqv4-large, parseqv4-tiny）。デフォルト/--liteの認識モデルより優先 |
--td_name |
テキスト検出モデル名（例: dbnetv2_1, dbnet）。デフォルトの検出モデルより優先 |
起動オプションの全一覧はAPIサーバーを参照してください。
APIキーを設定する¶
通常はYOMITOKU_STUDIO_API_KEYSにStudio用APIキーを設定します。
export YOMITOKU_STUDIO_API_KEYS="studio-user:0123456789abcdef"
yomitoku_server studio --host 127.0.0.1 --port 8000
StudioからのAPI呼び出しには、Proライセンスキーとは別のAPIキーを使用します。YOMITOKU_LICENSE_KEYとYOMITOKU_SECRET_KEYはProサーバー内だけに配置してください。
flowchart LR
B[YomiToku Studio] -->|Bearer APIキー| P[YomiToku-Pro API]
P -->|ライセンス確認・利用量| L[ライセンスサーバー]
K[Proサーバーの環境変数・Secret<br/>ライセンスキー／シークレットキー] -->|Proプロセスだけが読み込む| PAPIキーはProサーバー側とStudio側の接続設定にそれぞれ保存します。localhostや社内LAN内で利用する場合でも、意図しないクライアントからのアクセスを防ぐため、認証を有効にしてください。
キーの形式¶
複数のキーはカンマで区切ります。
name:は省略できます。省略したキーにはkey-1、key-2のような名前が付きます。
- キー：16文字以上。使用できる文字は英数字、
_、- - 名前：1～32文字。使用できる文字は英数字、
_、-
形式が不正な場合や名前が重複した場合、サーバーは起動しません。
一時キーを生成する¶
環境変数を設定せずに対話端末から起動すると、一時キーが端末に一度だけ表示されます。キーはサーバー停止時に失効します。
非対話環境では、--api-key-fileに生成したキーの出力先を指定できます。このオプションは、既存キーの読み込みには使用できません。
ファイルはパーミッション0600で新規作成されます。既存ファイルは上書きしないため、同じパスが存在すると起動エラーになります。固定キーを継続利用する場合はYOMITOKU_STUDIO_API_KEYSを使用してください。
Docker、systemdなどの非対話環境でキーを設定しない場合、/pingは利用できますが、/studio/v1/*は無効になります。Document Analyzer API・Table Semantic Parser APIの起動状態には影響しません。
認証を無効にする¶
開発環境で認証を無効にする場合は--no-authを指定します。
Danger
--no-authは、127.0.0.1などのloopbackアドレスにbindした開発環境でのみ使用し、LANやインターネットへ公開しないでください。
認証ヘッダー¶
Studio APIではBearerヘッダーを使用します。
APIキーが指定されていない場合、または一致しない場合はHTTP 401、Studio APIが無効な場合はHTTP 404になります。
CORSを設定する¶
ブラウザ版StudioからPro APIへ直接接続する場合は、StudioのOriginを許可します。
複数のOriginを許可する場合は、--cors-originを繰り返し指定します。
yomitoku_server studio \
--cors-origin https://studio-a.example.com \
--cors-origin https://studio-b.example.com
環境変数でも設定できます。
sequenceDiagram
participant B as Studio（ブラウザ）
participant P as YomiToku-Pro API
B->>P: OPTIONS（接続可否の確認）
P-->>B: 許可Origin・Method・Header
B->>P: Authorization + 文書
P-->>B: 解析レスポンスOriginはスキーム、ホスト、ポートの組み合わせです。https://studio.example.comとhttp://studio.example.comは別Originとして扱われます。CORSは未設定の場合は無効です。ワイルドカード*は指定できません。
CORSはブラウザ向けのアクセス制御であり、APIキー認証とは別に設定します。環境によってはブラウザのPrivate Network Access制限により、CORSに加えてHTTPSや同一Origin Proxyが必要になる場合があります。
Request IDを確認する¶
Pro APIはすべてのHTTPレスポンスにX-Request-IDを付与します。Studio、Access Proxy、Proの間でリクエストを追跡するために使用します。
sequenceDiagram
participant S as Studio
participant P as Access Proxy（任意）
participant A as YomiToku-Pro API
S->>P: X-Request-ID: client-request-123
P->>A: 同じIDを転送
A-->>P: X-Request-ID: client-request-123
P-->>S: X-Request-ID: client-request-123- 有効な
X-Request-IDを送信した場合は、レスポンスにも同じ値を返します X-Request-IDが未指定の場合、または形式が不正な場合はUUIDを生成します- 使用できる文字は英数字、
.、_、-で、最大128文字です - CORSプリフライトや認証エラーにも付与されます
障害やエラーについて問い合わせる際は、レスポンスのX-Request-IDを共有してください。Request IDはログ追跡専用で、認証や冪等性制御には使用されません。
解析リクエスト¶
解析APIはJPEG、PNG、TIFFの画像を1リクエストにつき1枚受け取ります。PDFは受け取りません。X-Yomitoku-Operation-ID、X-Yomitoku-Document-ID、X-Yomitoku-Page-IDを必ず指定してください。同じOperation IDを同じリクエストで再送しても二重計上されません。別のリクエストへ使い回すとHTTP 409を返します。
curl -X POST http://127.0.0.1:8000/studio/v1/document/analyze \
-H "Authorization: Bearer 0123456789abcdef" \
-H "Content-Type: image/png" \
-H "X-Yomitoku-Operation-ID: operation-1" \
-H "X-Yomitoku-Document-ID: document-1" \
-H "X-Yomitoku-Page-ID: page-1" \
--data-binary @page.png
レスポンスは解析結果と、後続の部分解析で使用するanalysis_idを返します。契約から残量を取得できる場合だけremaining_pagesも含まれます。Request IDはレスポンス本文ではなくX-Request-IDヘッダーで確認します。
解析前にページの回転(90 / -90 / 180度)を自動で検出・補正します。補正した場合はレスポンスにrotation(適用した角度)が含まれ、resultの座標は補正後の画像を基準とします(±90度では幅と高さが入れ替わります)。補正がない場合、rotationは省略されます。部分解析API(recognize-regions / analyze-regions)には、送信済みの元画像・補正後の画像のどちらを送っても構いません。元画像を送った場合はサーバーが記録済みの角度で補正してから処理します(領域座標は常に補正後の画像基準で指定します)。
帳票解析ではパスを/studio/v1/form/analyzeへ変更します。テンプレート適用時は?mode=ocr_onlyを指定すると、独立OCRパイプラインで回転補正、文字検出、文字認識だけを実行します。補正した角度と座標の扱いは通常の解析と同じです。この処理も全体解析として計上され、新しいanalysis_idを返します。
GET /studio/v1/capabilitiesは、上限のあるsubscription契約で利用状況を取得できる場合にusage_limitとusage_countを返します。Studioの接続設定では、この値を上限・現在利用数・残数のメーターとして表示します。値はライセンスサーバー側の集計遅延を含む概算です。
部分再OCRは/studio/v1/ocr/recognize-regions、表領域再解析は/studio/v1/form/analyze-regionsを使用します。詳しいリクエスト形式はReDocを参照してください。
モデル共有と利用量計上¶
Studioプロセスでは、Document AnalyzerとTable Semantic Parserが同じText DetectorとText Recognizerを使用します。Document固有・帳票固有のモデルは共有しません。別プロセスで起動した他のAPIサーバーともモデルを共有しません。
利用量は内部モデルの呼び出し回数ではなく、全体解析APIの成功単位で確定します。
| 操作 | 計上 |
|---|---|
| 文書解析の成功 | 1 |
| 帳票解析の成功 | 1 |
| 解析失敗 | 0 |
| 同じOperation ID・同じ入力の再送 | 追加0 |
| 同じOperation IDを別入力や別操作へ使用 | 推論前にHTTP 409、追加0 |
| outrightライセンス | 0 |
明示的なUsage Scope内では従来のモジュール単位計上を抑止するため、共有OCRモデルを複数回呼び出しても二重計上されません。重複記録はプロセスメモリに保持するため、サーバー再起動後をまたぐ重複排除は保証されません。