iHandify RestAPI について

I. 概要

iHandify RestAPI は、以下の3つのAIサービスを提供します。

1. 手書き文字認識 (Handwriting Text Recognition - iHTR)

手書きの内容を機械可読なテキストに変換します。
デジタルインクおよび画像入力の両方に対応しています。
対応言語
- 日本語
- 英語
- ベトナム語

2. 手書き式認識 (Handwriting Formula Recognition - iHFR)

手書きの式を認識し、LaTeX形式に変換します。
デジタルインクおよび画像入力の両方に対応しています。
対応分野
- 数学
- 化学
- 物理

3. 書写学習支援システム (Calligraphy Assistant System -iCAS)

デジタルインクで書かれた手書き文字を評価します。
主に以下の観点で評価を行います
- 書き順
- 書き方の正確さ
- 美しさおよびバランス

II. ベースURL

	https://api.ihandify.com/v1

III. 認証

すべてのリクエストは、有効な Scoped Public APIキーを使用して認証する必要があります。

APIキーは、サブスクリプションプランに基づいて特定のリソースへのアクセスを許可します。APIキーを取得するには、いずれかのプランに加入する必要があります。Scoped Public APIキーは、サブスクリプション設定で確認できる Secret APIキーを使用して生成できます。

フロントエンドからのリクエストには Scoped Public APIキーの使用を推奨し、Scoped Public APIキーの生成は Secret APIキーを用いてバックエンド側で安全に行うことを推奨します。 api_key_generation

有効なAPIキーが含まれていないリクエスト、削除済みまたは有効期限切れのキーを使用したリクエスト、またはサブスクリプションプランの範囲外のリソースにアクセスしようとしたリクエストは、Forbidden エラーを返します。

Scoped Public APIキーの生成

Scoped Public APIキーを生成するには、以下のエンドポイントに対して、リクエストヘッダーに Secret APIキーを含めて POST リクエストを送信します。

 curl -X POST https://api.ihandify.com/v1/plan/auth/generate-scoped-public-key \
 	-H "x-api-key: {SECRET_API_KEY}" \
 	-F "expireInSeconds=900"	# 任意: Scoped Public APIキーの有効期限（秒）を指定します（デフォルトは300秒＝5分、最小は1秒、最大は1800秒＝30分）

レスポンスには、生成された Scoped Public APIキーとその有効期限が含まれます。

 HTTP/1.1 200 OK
 Content-Type: application/json; charset=utf-8
 {
 	"data":{
 		"scopedPublicKey": "spk_cde88bc3267e3378677404121856330a4feb345c7712e04587cbaa2d9769583a",
 		"expiresIn": 900,
 		"expiresAt": "2026-04-02T05:27:04.5575279Z"
 	}
 }

APIキーの使用方法

iHandify RestAPI にリクエストを送信する際は、以下のように Scoped Public APIキーをリクエストヘッダーに含めてください。

	x-api-key: {SCOPED_PUBLIC_API_KEY}

IV. データ型

1. デジタルインク形式

デジタルインクとは、スタイラスやタッチデバイスから取得されたペンのストロークデータを指します。

	{
		"input": [[[536,368],[536,367],[534,366],[519,364],[497,364],[462,366],[432,376],[416,385],[396,402],[381,434],[384,447],[390,454],[396,454],[417,457],[433,454],[454,440],[469,421],[484,380],[486,366],[485,350],[485,342],[485,340],[485,342],[485,344],[485,350],[487,362],[488,379],[496,400],[502,406],[512,411],[523,413],[533,413],[544,409],[558,399],[562,395],[562,395]]]
	}

入力はデジタルインクデータであり、ストロークの配列として表現されます：

[strokes * [points * [x, y]]]

各ストロークは点の配列で構成されており、各点は (x, y) 座標によって定義されます。
x および y は、2次元座標系における位置を表す整数値です。

2. 画像形式

画像は、リクエストのContent-Typeに応じて、以下の2つの方法で送信できます。

2.1. オプションA：Base64画像（JSON）

Content-Type: application/json でリクエストを送信する場合は、この方法を使用します。

	{
		"input": "<base64-encoded-image>",	# 画像：Base64エンコードされた文字列（データURIスキームの接頭辞 data:image/png;base64, 等は含めないでください）
	}

2.2. オプションB：バイナリ画像（Multipart Form Data）

Content-Type: multipart/form-data でリクエストを送信する場合は、この方法を使用します。

対応フォーマット：

Windowsビットマップ - *.bmp, *.dib
GIFファイル - *.gif
JPEGファイル - *.jpeg, *.jpg
JPEG 2000ファイル - *.jp2
PNG（Portable Network Graphics） - *.png
WebP - *.webp
AVIF - *.avif
ポータブル画像フォーマット - *.pbm, *.pgm, *.ppm, *.pxm, *.pnm
Sunラスター - *.sr, *.ras
TIFFファイル - *.tiff, *.tif

例 (curl)

	curl -X POST https://api.ihandify.com/v1/ihtr/recognize \
		-H "x-api-key: spk_cde88bc3267e3378677404121856330a4feb345c7712e04587cbaa2d9769583a" \
		-F "input=@ja_sample.jpg"

V. 運用ガイドライン

3. リクエストサイズ制限

すべてのユーザーに対して最適なパフォーマンスと信頼性を確保するため、本APIではリクエストサイズおよび処理に関する制限を設けています。

これらの制限を超えた場合、APIは 413 Content Too Large エラーを返します。

ペイロード制限

リクエストペイロードには以下の制限が適用されます。

デジタルインク：リクエストボディあたり最大 512 KB
画像：
- Base64エンコード画像（application/json）の場合：最大 2 MB
- multipart/form-dataで送信される画像の場合：最大 5 MB

ペイロードサイズとパフォーマンスに関するガイドライン

レスポンス時間は一般的に入力ペイロードのサイズに比例して増加します。最適なパフォーマンスを得るため、以下の点を推奨します。

画像入力

可能な限り画像サイズを 512 KB以下に抑える
以下の方法で画像を最適化する
- JPEG圧縮を使用してファイルサイズを削減する
- 解像度を下げる（推奨：150～200 dpi）
- カラーが不要な場合はグレースケールに変換する

デジタルインク（ストローク）入力

最適なパフォーマンスのため、インクデータは 100 KB以下に抑える
以下の方法でペイロードサイズを削減する
- 点簡略化アルゴリズム（例：Ramer–Douglas–Peucker法）を使用して冗長な点を削除する

4. プライバシー

すべてのAPIエンドポイントは、リクエスト内で improveProduct パラメータを受け付けており、リクエストデータの取り扱いや、iLaboによるサービス改善への利用可否を制御できます。

例

improveProduct を無効化したリクエスト例：

	{
		"improveProduct": false
	}

データ利用方針

improveProduct のデフォルト値は true です。

この場合、リクエストデータは、サービス品質の向上および不具合解析を目的として、当社の品質保証担当者（QAチーム）により参照・利用される場合があります。

improveProduct を false に設定した場合、リクエストデータは以下の通り取り扱われます：
- サービス品質向上の目的では一切利用されません
- リクエスト処理完了後、速やかに削除されます
- デバッグ、分析、その他いかなる目的においても利用されません