API リファレンス
プレビュー、挿入確定、周期表のエンドポイント。識別子は翻訳せず、そのまま送信します。
認証と Origin
すべての /v1/* に X-Formulix-Chave を送ります。有効なキーと、アカウントの登録ドメイン（サブドメインを含む）に属する Origin ホスト名が必要です。Origin はブラウザーが付与するため JavaScript で手動設定しないでください。OPTIONS は登録済みドメインまたは開発用 Origin、GET/POST、Content-Type/X-Formulix-Chave を許可しますが、実リクエストではキー所有者のドメインを再検証します。
応答は Vary: Origin と Cache-Control: no-store を使い、許可した Origin を反映します（ワイルドカードは不使用）。拒否がブラウザーでは CORS エラーだけに見えることがあります。キーは公開用であり管理用ではありません。外部スクリプトは Origin を偽装できます。失効・ドメイン変更の反映は通常約5秒です。
運営者から提供された HTTPS API URL とアカウントの公開キーを設定し、管理画面にエディターのドメインを登録します。サブドメインも対象です。https://api.formulix.example と YOUR_PUBLIC_KEY は説明用のプレースホルダーで、実在する接続先やキーではありません。
POST /v1/calc — プレビュー
JSON は { op, dados, idioma, notacao }。op は操作、dados はそのパラメーターです。言語の既定値は en、notacao は任意。例：{"decimal":"."}。応答は操作により HTML、LaTeX、SVG、補助データになります。成功時はプレビュー1回、挿入0回。
const response = await fetch('https://api.formulix.example/v1/calc', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Formulix-Chave': 'YOUR_PUBLIC_KEY'
},
body: JSON.stringify({
op: 'word', dados: { html: '<p>数式のない文章</p>' },
idioma: 'ja'
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.erro);
// { eqs: [] }操作識別子：divisao, multiplicacao, adicao, subtracao, ruffini, mmc, fatoracao, fracoes, regra3, eq1, eq2, sistema, tabela, estudo, grafico, qeq, qmassa, qdist, qvid, qtit, qpaul, qorg, qcad, qtab, word。dados の形式は操作により異なり、共通の単一スキーマはありません。アダプターの生成するリクエストを使用してください。
POST /v1/inserir — 確定
tipo、下記のデータ、任意の idioma/notacao を送ります。応答は JSON で共通の包み構造はありません。プレビューと同じヘッダーを使用します。
| tipo | 入力 | 出力と利用量 |
|---|---|---|
| formula | latex; bloco は任意 | { html } / MathML。空でない LaTeX、最大20,000文字。1挿入。 |
| word | html; rtf は任意 | { html }。変換した数式ごとに1回、数式なしは0回。 |
| grafico | グラフ操作の dados | { svg, w, h, funcoes, alt }。1挿入。 |
| conta / quimica | op と dados; grafico/word 以外の認識済み op | 操作により { html }、{ bloco: true, html } または { svg, w, h, alt }。1挿入。 |
{"tipo":"formula","latex":"x^2","bloco":false,"idioma":"ja"}成功例：{"html":"<math ...>...</math>"}。クライアントが SVG を PNG に変換し、利用するプラットフォームへアップロードします。計算 API は画像を保存しません。再編集を含む受理された確定ごとに課金カウントが生じ、識別子による冪等性はありません。初回の成否が不明な確定を自動再送しないでください。
GET /v1/tabela?idioma=ja
周期表の { z, s, nome, pos, cor } 配列を返します。公開データでもキーと有効な Origin が必要です。挿入・プレビューは加算しませんが、毎分の制限には含まれます。言語の既定値は英語です。
制限
- 本文は最大15 MiB。413 応答後に接続を閉じる場合があります。
- キーごと・プロセスごと毎分1,200リクエスト。プレビューと周期表を含み、複数プロセスで共通の上限ではありません。
- プランは月500 / 5,000 / 25,000回、ネットワークは数値上限なし。無料版はアカウントとドメインの両方、有料はアカウントで合算します。
- 開発用は既定で月300挿入/アカウント、FORMULIX_DEV_LIMITE で変更可能。localhost、.localhost、127.0.0.1、[::1]、.test を含み、有効なキーは必須です。
- プロセス間同期は通常5秒ごと。全プロセス共通のリクエスト単位トランザクションカウンターではありません。月の基準は UTC です。
エラー
アプリケーションのエラーは {"erro":"message"}。計算の検証メッセージは翻訳される場合があります。
| HTTP | ドキュメント |
|---|---|
| 400 Invalid JSON. | JSON が不正、または本文がオブジェクトでない |
| 401 Invalid key. | キーなし・無効・失効 |
| 402 Monthly insertion limit reached. | 月間のプラン枠または開発枠の上限 |
| 403 Origin not allowed for this key. | キーに対して Origin が不許可。preflight は本文なしの場合あり |
| 404 Unknown route. / Unknown operation. | 不明なルートまたは操作 |
| 413 Request too large. | 本文サイズ超過 |
| 422 | 入力が無効。erro を確認 |
| 429 Rate limit reached. | 毎分リクエスト上限 |
| 500 Internal error. | 内部エラー |
/saude は認証なしで {"ok":true} を返しますが、キーによる利用可否は確認しません。
日本語 UI は ja を指定します。小数点は「.」、三角関数は sin/tan、座標は (2.5, -0.25)、解の添字は x₁/x₂、割り算は長除法です。「筆算」から加算・減算・乗算・除算を扱えます。小学校の繰り上がり・繰り下がり、中学校の比例・連立方程式、高校の二次関数やモル質量の教材に合わせて例題を選んでください。学校独自の筆算レイアウトの完全再現は保証されません。一部の UI やエラーは英語で表示されます。