テキスト翻訳

包括的な開発者ガイドとベストプラクティスで、すばやく開発を始められます。

チュートリアル

一括 JSON 翻訳から SSE 逐次ストリーミング、辞書連携まで、テキスト翻訳の実戦フローをまとめます。

本チュートリアルは POST /api/v1/translations/text を軸に、3 つのシナリオを順に解説します：一括 JSON 翻訳、SSE 逐次配信、辞書連携。それぞれ curl 例と注意点を併載します。

API キーを準備する

コンソールでキーを作成し、HTTP ヘッダーに X-API-Key として付与します。キーは一度しか表示されないため、ソースコードやフロントエンドのバンドルに直接書かず、環境変数で注入することを推奨します。

キーを環境変数に格納します。以降の例はすべて $ABESTAR_API_KEY を参照します。

bash

export ABESTAR_API_KEY="sk_live_..."

シナリオ 1:一括 JSON 翻訳

既定の stream=false ではモデルの完了を待ってから完全な結果を一括返却します。短文や後段処理向けです。入力上限は 5000 文字、超過時は 400 validation_error が返ります。

JSON モードの curl 例。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "今天的會議改到下午三點。",
    "target_language": "en",
    "source_language": "auto"
  }'

応答には翻訳テキスト、自動検出されたソース言語（明示時は null）、累積クォータ使用率（usage.quota_percent.used、0–100）、強制置換が実際に適用された回数が含まれます。

成功応答例（HTTP 200）。

json

{
  "translated_text": "Today's meeting is rescheduled to 3 PM.",
  "detected_source_lang": "zh-TW",
  "usage": {
    "quota_percent": {
      "used": 12
    }
  },
  "forced_replacement_count": 0
}

追加機能パラメータ

以下のパラメータはすべて任意で、JSON / SSE いずれのモードとも自由に組み合わせられます。省略時は既定値が適用されます。音声認識エンドポイントも同じ共通パラメータを受け付けます。両章の表は列と並び順を意図的に揃えてあり、左右で見比べられます。

上位 7 行は音声認識エンドポイントと共通、最終行は翻訳専用です。

パラメータ	型	既定値	説明
model	string	"PSSC-V1-251215"	翻訳モデルコード。利用可能な一覧は GET /translations/models で取得できます。
domain	string	"general"	内容領域のヒント（"legal" / "medical" / "gaming" など）。専門文脈での語彙選択を補助します。
context	{ speech: string }[]	[]	会話の文脈や先行発話を時系列順で渡します。代名詞や主語省略の訳出精度が上がります。
harm_content_filter	boolean	false	有害コンテンツフィルタを有効化します。拒否時は 400 content_policy_violation。
punctuation	boolean	false	訳文の句読点を自動補完します。音声認識エンドポイントでは同名パラメータの既定が true であり、両者で異なります。
number_format	"spoken" \| "arabic"	"spoken"	数字の書き起こし方式：spoken は口語表記、arabic はアラビア数字（1234）。
date_format	"natural" \| "yyyy-MM-dd" \| "yyyy/MM/dd" \| "MM/dd/yyyy" \| "dd-MM-yyyy"	"natural"	日付の表現方式：natural は目的言語の慣例に従い、その他は固定テンプレートです。
source_language	string	"auto"	翻訳エンドポイント専用。ソース言語コード、または auto のままモデルに自動検出させます。

ドメインヒント・会話文脈・自動句読点・数字表記・日付形式をまとめて使う例。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "上一季營收成長了一成二，下次會議訂在二〇二六年三月五日。",
    "target_language": "en",
    "domain": "finance",
    "context": [{ "speech": "我們今天先討論第一季的營收。" }],
    "punctuation": true,
    "number_format": "arabic",
    "date_format": "yyyy-MM-dd",
    "harm_content_filter": true
  }'

シナリオ 2:SSE ストリーミング

対話 UI や長文には stream=true による逐次出力が適しています。応答は text/event-stream で、イベント順序は head（ソース言語）→ chunk*（テキスト片、0〜複数件）→ tail（終了マーカー）→ meta（使用量）。失敗時は任意の時点で error イベントが残りを置換し、ストリームを終了します。

SSE モードの curl 例。-N で curl のバッファリングを無効化し、イベントを逐次出力します。

bash

curl -N -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "今天的會議改到下午三點。",
    "target_language": "en",
    "stream": true
  }'

SSE 解析例:fetch + ReadableStream + TextDecoder。各イベントは空行で区切られます。

javascript

const res = await fetch("https://abemono.abestar.com.tw/api/v1/translations/text", {
    method: "POST",
    headers: {
        "X-API-Key": process.env.ABESTAR_API_KEY,
        "Content-Type": "application/json",
        Accept: "text/event-stream",
    },
    body: JSON.stringify({
        text: "今天的會議改到下午三點。",
        target_language: "en",
        stream: true,
    }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let output = "";

while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    const events = buffer.split("\n\n");
    buffer = events.pop() ?? "";

    for (const evt of events) {
        const line = evt.split("\n").find((l) => l.startsWith("data: "));
        if (!line) continue;
        const payload = JSON.parse(line.slice(6));

        switch (payload.type) {
            case "head":
                console.log("source:", payload.data.source_lang);
                break;
            case "chunk":
                output += payload.data;
                break;
            case "tail":
                console.log("done:", output);
                break;
            case "meta":
                console.log("usage:", payload.data.usage);
                break;
            case "error":
                console.error(payload.data.code, payload.data.message);
                break;
        }
    }
}

SSE の業務エラーでも HTTP status は 200

ストリーミング接続が確立すると HTTP ステータスは 200 に固定されます。モデルエラーやタイムアウトはステータスを書き換えず、error イベント（code / message / request_id を含む）として返却されます。HTTP ステータスではなくイベント payload で成否を判定してください。

シナリオ 3:辞書を併用する

翻訳エンドポイントは2種類の辞書を受け付けます。vocabulary はソフトヒントとして扱われ、マッチした語彙はモデルに対して適切な訳語として渡されます。forced_replacement は後処理置換で、翻訳完了後に文字列置換を適用します。どちらも UUID を vocabulary_dictionary_id / forced_replacement_dictionary_id に指定します。

JSON モードでは両方の辞書を同時に指定できます。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "請把這份合約交給法務組長確認。",
    "target_language": "en",
    "vocabulary_dictionary_id": "f3c1e9a2-9c2b-4f7a-9d3a-7e2b8a1c4d5e",
    "forced_replacement_dictionary_id": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a"
  }'

SSE と forced_replacement は併用不可

後処理置換は完全出力を要するため、逐次配信とは原理的に両立しません。stream=true と forced_replacement_dictionary_id を同時送信すると、翻訳処理に入る前に 400 validation_error が返ります。ストリーミングで置換が必要な場合は JSON モードに戻すか、クライアント側で置換してください。

辞書の詳細

作成、一括作成、CRUD、2 種類の辞書の使い分けについては「辞書操作の手順」と「辞書の概念」を参照してください。