プロビジョニングジョブを作成
手元にあるソースを送れば、すぐにエンジンが返ってきます。POST /jobs/provisioning には新しいエンジン名と最大 10 件のソース（クロール対象のリンクまたは生テキスト）を渡し、レスポンスとしてエンジンIDを含む 202 Accepted を受け取ります。AI がコンテンツを読み終えるまで待つ必要はありません。呼び出しが返った瞬間にエンジンは作成されており、設定はジョブの進行に合わせて反映されます。
POST /jobs/provisioningこのページでは、作成リクエストのパラメータ、リクエスト形式、そして 202 レスポンスを扱います。非同期プロビジョニングが初めてなら、まずは Async Provisioning API overview で全体像をつかんでください。良いソースの条件は Source types、そこから AI が何を抽出するかは What the AI extracts で説明しています。
認証
API キーは X-API-Key ヘッダーで渡します。キーは組織スコープで、組織内のすべてのエンジンにアクセスできます。詳しくは Authentication をご覧ください。
パラメータ#
必須なのは engine.name だけです。それ以外はエンジンが何を学習するかを決める項目で、すべて省略すればデフォルト設定のままのクリーンなエンジンが作成されます。
| パラメータ | 型 | 説明 |
|---|---|---|
engine.name | string | 新しいローカライゼーションエンジンの名前。 |
engine.description | string（任意） | エンジンの説明を自由記述で指定します。 |
locales | string[]（任意） | 設定対象となる BCP-47 のターゲットロケール。例: ["es", "ja", "de"]。 |
sources | array（任意） | 解析対象のソースを最大 10 件まで指定できます。各ソースは link（プラットフォームがクロールする URL）または content（生テキストまたは markdown）です。詳しくは Source types を参照してください。 |
callbackUrl | string（任意） | 完了結果の受信用 HTTPS webhook URL。HTTPS のみ対応しており、HTTP のコールバック URL は拒否されます。詳しくは Webhook delivery を参照してください。 |
リクエスト#
ソースは { type, payload } オブジェクトです。link ソースには、ブランドガイドライン、スタイルガイド、製品ドキュメントなど、十分な文脈があるページを指定してください。直接貼り付けられる用語ルールやトーンルールには content を使います。以下のリクエストはその両方を組み合わせた例で、クロール対象の 2 ページと明示的なルールの 1 ブロックが含まれています。
const response = await fetch("https://api.lingo.dev/jobs/provisioning", {
method: "POST",
headers: {
"X-API-Key": process.env.LINGO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
engine: {
name: "Acme Corp Engine",
description: "Production localization engine for acme.com",
},
locales: ["de", "fr", "ja", "es"],
sources: [
{ type: "link", payload: "https://acme.com/brand-guidelines" },
{ type: "link", payload: "https://acme.com/docs/style-guide" },
{
type: "content",
payload:
"Brand name 'Acme' is never translated. Use formal tone in German (Sie-form). Product names: AcmeFlow, AcmeSync, AcmeVault - always keep in English.",
},
],
callbackUrl: "https://your-app.com/webhooks/provisioning",
}),
});
const { jobId, engineId, status } = await response.json();
// 202 back right away.
// status: "in_progress" – the AI is reading your sources.
console.log(engineId); // "eng_X1y2Z3a4B5c6D7e8" – usable right nowレスポンス（202 Accepted）#
この呼び出しはクロールや解析の完了を待たずに返り、進行状況を追跡するためのジョブIDと、その時点ですでに有効なエンジンIDを受け取れます。
{
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"engineId": "eng_X1y2Z3a4B5c6D7e8",
"status": "in_progress"
}| フィールド | 説明 |
|---|---|
jobId | プロビジョニングジョブID（pjb_ プレフィックス）。進行状況は connecting a WebSocket でリアルタイムに追跡でき、完了時には webhook で結果を受け取ることもできます。 |
engineId | 新しいエンジンのID（eng_ プレフィックス）。すぐに利用でき、AI が抽出した設定はジョブの進行中にこのエンジンへ反映されます。 |
status | ソースを指定した場合は in_progress、指定しない場合は completed です（下記参照）。 |
これがただ待つだけの非同期呼び出しではなく、実行する価値がある理由は、engineIdが同じ202で返され、しかもその時点ですぐに実在するエンジンを指していることです。保存しておくことも、そのまま同期 Localizeリクエストを送ることも、AIがソースを1つも読み終える前にアプリに組み込むこともできます。ブランドボイス、用語集項目、ルールが抽出されるたびに、プラットフォームはそれらをその同じエンジンに適用します。つまり、設定がそろう前からエンジン自体は存在しているのです。ジョブで実際に何が作成されたのかを正確に知りたい場合は、AIが抽出する内容をご覧ください。
ソースがなくても、待たずにエンジンを受け取れます。
sources を省略するとクロール対象がないため、エンジンはデフォルトのモデル設定で作成され、同じレスポンス内で status: "completed" と一緒に返されます。自分で設定する空のエンジンが欲しいときは、これが最短ルートです。1 回の呼び出しで、すぐ使える engineId が手に入り、追跡すべきバックグラウンドジョブも発生しません。