文字翻譯

這裡提供完整的開發指南與最佳實踐，幫助您快速上手。

教學

從一次性 JSON 翻譯到 SSE 逐段串流，再到字庫加成，整理一段完整的文字翻譯實戰流程。

本教學以 POST /api/v1/translations/text 為主軸，逐步涵蓋三個情境：一次性 JSON 翻譯、SSE 逐段串流、以及搭配字庫的進階用法。每個情境都附 curl 範例與重點注意事項。

準備 API 金鑰

在控制台建立一把金鑰，並在 HTTP Header 帶入 X-API-Key。金鑰僅顯示一次，建議透過環境變數注入，避免寫死於原始碼或前端打包檔。

把金鑰放進環境變數，後續範例皆引用 $ABESTAR_API_KEY。

bash

export ABESTAR_API_KEY="sk_live_..."

情境一:一次性 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 任一模式自由組合；未提供時套用預設值。語音辨識端點也接受同一批共通參數，兩章的表格欄位與排序刻意保持一致，方便左右對照。

前七列為兩端點共通參數，最後一列為翻譯端點專屬。

參數	型別	預設	說明
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
  }'

情境二:SSE 串流

對話介面或長段文字適合用 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。模型錯誤、逾時等情況不會改寫 status，而是改以 error 事件送回（包含 code、message、request_id）。請以事件 payload 判斷成敗，不要只看 HTTP 狀態。

情境三:搭配字庫

翻譯端點接受兩種字庫: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 與兩種字庫類型的選用建議，請見「字庫操作教學」與「字庫概念」兩章。