Studio API Connection¶
YomiToku-Pro provides authentication, CORS, and Request ID support for connections from YomiToku Studio.
The Studio API runs as a separate process from the Document Analyzer and Table Semantic Parser APIs. One Studio endpoint provides both document and form analysis.
| Endpoint | Operation |
|---|---|
GET /ping |
Health check |
GET /studio/v1/capabilities |
Supported operations and limits |
POST /studio/v1/document/analyze |
Document OCR and layout analysis |
POST /studio/v1/form/analyze |
Form and table analysis (?mode=ocr_only runs detection and recognition only) |
POST /studio/v1/ocr/recognize-regions |
Partial re-OCR of specified text regions (not billed) |
POST /studio/v1/form/analyze-regions |
Cell/structure reanalysis of specified table regions (not billed) |
Models and lite mode¶
The Studio server accepts the same model-selection options as the Document Analyzer and Table Semantic Parser servers. They apply to both the document and form pipelines, which share one Text Detector and one Text Recognizer.
# Start with lightweight models for CPU (--lite is enabled automatically on CPU)
yomitoku_server studio --lite --host 127.0.0.1 --port 8000
# Start with explicit model names
yomitoku_server studio --tr_name parseqv4-large --td_name dbnetv2_1 --host 127.0.0.1 --port 8000
| Option | Description |
|---|---|
-l, --lite |
Fast inference with lightweight models (parseqv4-tiny dynamic-width recognizer). On CPU the detector also runs on ONNX |
--tr_name |
Text recognizer model name (e.g. parseqv4, parseqv4-large, parseqv4-tiny). Overrides the default / --lite recognizer |
--td_name |
Text detector model name (e.g. dbnetv2_1, dbnet). Overrides the default detector |
See API Server for the full list of startup options.
Configure an API key¶
For normal use, set a Studio API key in YOMITOKU_STUDIO_API_KEYS.
export YOMITOKU_STUDIO_API_KEYS="studio-user:0123456789abcdef"
yomitoku_server studio --host 127.0.0.1 --port 8000
Studio uses an API key that is separate from the Pro license credentials. Keep YOMITOKU_LICENSE_KEY and YOMITOKU_SECRET_KEY on the Pro server.
flowchart LR
B[YomiToku Studio] -->|Bearer API key| P[YomiToku-Pro API]
P -->|License checks and usage| L[License server]
K[Pro server environment or secret store<br/>License key and secret key] -->|Read only by the Pro process| PStore the API key in the Pro server configuration and the Studio connection settings. Keep authentication enabled even on localhost or an internal LAN to prevent access from unintended clients.
Key format¶
Separate multiple keys with commas.
The name: prefix is optional. Unnamed keys receive names such as key-1 and key-2.
- Key: at least 16 characters; letters, digits,
_, and-are allowed - Name: 1–32 characters; letters, digits,
_, and-are allowed
The server will not start if a key has an invalid format or a name is duplicated.
Generate a temporary key¶
When you start the server from an interactive terminal without setting the environment variable, a temporary key is displayed once. The key expires when the server stops.
In a non-interactive environment, use --api-key-file to specify where the generated key should be written. This option cannot read an existing key.
The file is created with mode 0600. Existing files are not overwritten, so startup fails if the path already exists. Use YOMITOKU_STUDIO_API_KEYS when you need a persistent key.
If no key is configured in a non-interactive environment such as Docker or systemd, /ping remains available but /studio/v1/* is disabled. This does not affect a separately running Document Analyzer or Table Semantic Parser API.
Disable authentication¶
Use --no-auth to disable authentication in a development environment.
Danger
Use --no-auth only in a development environment bound to a loopback address such as 127.0.0.1. Do not expose this configuration to a LAN or the internet.
Authentication header¶
The Studio API uses a Bearer header.
A missing or incorrect API key returns HTTP 401. A disabled Studio API returns HTTP 404.
Configure CORS¶
When browser-based Studio connects directly to the Pro API, allow the Studio origin.
Repeat --cors-origin to allow multiple origins.
yomitoku_server studio \
--cors-origin https://studio-a.example.com \
--cors-origin https://studio-b.example.com
You can also use an environment variable.
sequenceDiagram
participant B as Studio (browser)
participant P as YomiToku-Pro API
B->>P: OPTIONS (connection check)
P-->>B: Allowed origin, method, and headers
B->>P: Authorization + document
P-->>B: Analysis responseAn origin is the combination of scheme, host, and port. For example, https://studio.example.com and http://studio.example.com are different origins. CORS is disabled when no origin is configured, and the * wildcard is not supported.
CORS controls browser access and is configured separately from API key authentication. Depending on the environment, browser Private Network Access restrictions may also require HTTPS or a same-origin proxy.
Check the Request ID¶
The Pro API adds X-Request-ID to every HTTP response. Use it to trace a request across Studio, an access proxy, and Pro.
sequenceDiagram
participant S as Studio
participant P as Access proxy (optional)
participant A as YomiToku-Pro API
S->>P: X-Request-ID: client-request-123
P->>A: Forward the same ID
A-->>P: X-Request-ID: client-request-123
P-->>S: X-Request-ID: client-request-123- If a valid
X-Request-IDis sent, the response returns the same value - If the header is missing or malformed, the server generates a UUID
- The value may contain letters, digits,
.,_, and-, up to 128 characters - CORS preflight and authentication error responses also include the header
Include the response X-Request-ID when reporting an error. Request IDs are used only for log correlation, not for authentication or idempotency.
Analysis requests¶
The analysis endpoints accept one JPEG, PNG, or TIFF image per request; PDF is not accepted. Supply X-Yomitoku-Operation-ID, X-Yomitoku-Document-ID, and X-Yomitoku-Page-ID. Retrying the same request with the same operation ID is not billed twice. Reusing it for a different request returns 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
The response contains the analysis result and an analysis_id for subsequent partial operations. remaining_pages is included only when the subscription quota is available. The Request ID is returned in the X-Request-ID response header, not in the response body.
Page rotation (90 / -90 / 180 degrees) is detected and corrected automatically before analysis. When a correction was applied, the response includes rotation (the applied angle) and the coordinates in result refer to the corrected image (width and height are swapped for ±90 degrees). The field is omitted when no correction was applied. The partial APIs (recognize-regions / analyze-regions) accept either the original image or the corrected one; an original image is rotated by the recorded angle on the server before processing (region coordinates are always specified in the corrected frame).
Use /studio/v1/form/analyze for form analysis. When applying a template, add ?mode=ocr_only to run rotation correction, text detection, and text recognition through the standalone OCR pipeline. Rotation and result coordinates follow the same contract as full analysis. This is still billed as a full analysis and returns a new analysis_id.
For a subscription with a finite limit, GET /studio/v1/capabilities includes usage_limit and usage_count when the usage estimate is available. Studio displays these values as the limit, current usage, and remaining-page meter in the connection settings. The values are advisory and may include aggregation delay from the license service.
Use /studio/v1/ocr/recognize-regions for partial OCR and /studio/v1/form/analyze-regions for table-region reanalysis. See ReDoc for the multipart request contracts.
Model sharing and usage counting¶
The Studio process shares one Text Detector and one Text Recognizer between its Document Analyzer and Table Semantic Parser pipelines. Pipeline-specific models are not shared, and no model instance is shared with other API server processes.
Usage is finalized per successful full-analysis API operation, not per internal model invocation.
| Operation | Count |
|---|---|
| Successful document analysis | 1 |
| Successful form analysis | 1 |
| Failed analysis | 0 |
| Retry with the same operation ID and input | No additional count |
| Reuse of an operation ID for another input or operation | HTTP 409 before inference; no count |
| Outright license | 0 |
The explicit Usage Scope suppresses the conventional module-level counting, so calling shared OCR models does not result in duplicate counts. Deduplication state is held in process memory and does not survive a server restart.