音声文字起こしと翻訳のジョブ

以下の例では、SERVICEをspeech_to_textまたはtranslateに、JOB_IDを返されたUUIDに置き換えてください。すべての操作には、認証で説明するアカウントの認証情報が必要です。すべての操作の範囲は、その認証情報を所有するアカウント内に限定されます。ジョブはどちらのAPIホストからも取得できますが、ホストごとにレスポンスの外側の構造が異なるため、一貫して同じホストを使用してください。

ホスト	成功時	エラー時
`api.multi.tel`	`{"status":"success","data":{...}}`	`{"status":"error","code":"...","message":"...","requestId":"..."}`
`api.multitel.net`	`{"status":{"code":200},"response":{...}}`	`{"status":{"code":409},"response":{"code":"idempotency_conflict"}}`

ホストapi.multitel.netでは、認証エラー（401）はこの外側の構造を適用する前に返され、本文の形式が異なる場合があります。レスポンスを解析する前にHTTPステータスを確認してください。

認証

すべてのリクエストにアカウントの認証情報を含める必要があります。ジョブ、冪等性キー、制限、使用量、料金は、その認証情報を所有するアカウントに属します。両ホストでそのアカウントのすべての認証情報に共通して適用され、どの認証情報でリクエストを送信したかには依存しません。

HTTP Basic（Authorization: Basicまたはcurl --user）。パスワード型のAPIアカウント、サブアカウント、またはご自身のアカウントへのログイン情報を使用できます。専用のAPIアカウントを推奨します。ユーザー名にコロンは使用できず、ユーザー名とパスワードはいずれも空にできません。
Bearerトークン（Authorization: Bearer YOUR_TOKEN）。トークン型のAPIアカウントで使用できます。トークン型APIアカウントにはIP制限が必須で、リクエストは許可されたアドレスから送信する必要があります。両APIホストは、アカウントに設定されたIPv4アドレスとCIDR範囲を受け付けます。トークンをBasic認証のパスワードとして送信することはできません。使用するホストでトークンが機能することを確認してください。

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

APIアカウントにIPアドレス制限がある場合は、許可されたアドレスからリクエストを送信してください。認証情報がない場合や無効な場合は401が返されます。ホストapi.multitel.netでは、トークン型アカウントの認証情報をBasic形式で送信した場合など、認証情報自体は有効でもこれらのサービスを使用できない場合に403とunsupported_transcription_principalまたはunsupported_translation_principalが返されます。ホストapi.multitel.netに同じアドレスから繰り返し認証に失敗すると、そのアドレスがブロックされる場合があります。再試行する前に認証情報を修正してください。

完了まで定期的に確認する

次のリクエストを送信します：GET /v3/SERVICE/JOB_ID。ポーリングの頻度は3秒に一回以下にすることを推奨します。レスポンスの外側の構造が示すのはリクエストの状態です。処理が完了したかどうかは、内部のジョブのstatusを確認してください。

ステータス	意味
`queued`	受け付け済みで待機中です。同じアカウントのジョブは、他のアカウントと順番を交代しながら、一件ずつ処理されます。
`running`	処理中です。`progress`は`null`になる場合があります。nullだけでは、ジョブが停止したことを意味しません。
`completed`	結果を取得できます。保存し、重要な詳細を元の内容と照合してください。
`failed`	次の項目を確認してください：`failureCode`。失敗したジョブには課金されません。原因を修正して新しいキーで送信してください。同じキーを再送すると、同じ失敗済みジョブが返されます。
`awaiting_payment`	処理は完了しましたが、前払い残高が料金を賄えませんでした。結果は保存されていますが、ジョブの精算が完了するまで提供されません。

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

ホストapi.multitel.netでは、HOSTをhttps://api.multitel.netに設定し、.response.idを.data.idの代わりに読み取ってください。

結果が不明なリクエストを安全に再試行する

送信がタイムアウトした場合や429または5xxステータスが返された場合は、同じ入力を同じ冪等性キーで再送してください。どちらのホストでも、ジョブが受け付けられた後にレスポンスが失われたり、エラーに置き換わったりする可能性があります。同じキーで再送すると、ジョブが存在する場合はそのジョブが返されます。同じキーを異なる入力で再利用すると、409とidempotency_conflictが返されます。有料サービスが無効な場合の503や、読み取れない音声ファイルに対する500など、毎回繰り返されるエラーもあるため、数回試しても失敗する場合は中止してください。

キーを変更した場合の動作は、サービスによって異なります。

音声文字起こしでは、新しいキーによって新しいジョブが作成され、処理が正常に完了すると別途課金されます。元のキーは、処理が更新された後も元のジョブを返し続けます。
翻訳では、同一の内容で新しいキーを使用すると、キュー内、処理中、完了済み、支払い待ちの一致するジョブが、新たな課金なしで返されます。以前のジョブが失敗した場合や処理バージョンが変わった場合は、新しいジョブが作成されます。処理バージョンの変更後に元のキーで翻訳を再試行すると409が返されるため、元のジョブIDを保持し、そのジョブを直接取得してください。

残高を追加して結果を取得する

ステータスがawaiting_paymentのジョブでは、残高がジョブのcostUsdを次の$0.00001単位に切り上げた額以上になるよう入金し、次のリクエストを送信してください：POST /v3/SERVICE/JOB_ID/settle。引き落としは$0.00001単位で行われ、同じサービスの過去のジョブから繰り越された端数も含まれるため、引き落とし額はcostUsdを$0.00001未満の範囲で上回る場合があります。ホストapi.multi.telではJSONの{}または空の本文を送信してください。本文にプロパティが一つでも含まれていると400で拒否されます。ホストapi.multitel.netでは本文が無視されます。精算によって保存済みの結果が提供され、文字起こしや翻訳は再実行されません。レスポンスにはジョブが含まれます。ステータスがcompletedであることを確認してください。残高が依然として不足している場合、ジョブはawaiting_paymentのままで、レスポンスもHTTP 200のままです。

音声文字起こしでは、既に完了したジョブを精算すると、duplicate: trueを付けてそのジョブが返されます。キュー内、処理中、失敗済みのジョブを精算すると、409とtranscription_not_awaiting_paymentが返されます。翻訳では、それ以外のステータスのジョブを精算すると、ジョブが変更されずに返されます。精算は有料処理が有効な場合にのみ利用できます（それ以外は503）。支払い待ちのジョブは予約済み費用として計上されるため、前払いアカウントでは、精算するまで新しい有料ジョブの送信が402でブロックされる場合があります。

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

使用量を確認する

次のリクエストを使用します：GET /v3/SERVICE/usage。任意のパラメーターfromとtoは、YYYY-MM-DD形式のUTC日付で、開始日と終了日の両方が含まれます。省略した場合、fromの既定値は今日の30日前、toの既定値は今日（UTC）です。toはfromより前にできず、日付の間隔は最大366日（最大367日付）です。無効な暦日、逆順または長すぎる範囲は400を返します。ホストapi.multi.telでは、他のクエリパラメーターも同様に拒否されます。

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

レスポンスにはmode、currency（USD）、from、toとdaysが含まれます。最後の項目は新しい順に並んだリストです。

音声文字起こしのエントリーは、日付とソースごとにまとめられます。含まれる項目はdate、source（api、またはHosted PBXの録音の場合はhpbx）、files、audioSeconds、billedSeconds、accruedUsdとdebitedUsdです。
翻訳のエントリーは、日付、ソース、エンジンごとにまとめられます。含まれる項目はdate、source、engine、jobs、sourceCharacters、accruedUsdとdebitedUsdです。

accruedUsdは小数点以下九桁の正確な費用、debitedUsdは小数点以下五桁の引き落とし額です。使用量は、各ジョブの料金が精算されたUTC日付で記録されるため、キュー内、処理中、失敗済み、支払い待ちのジョブは表示されません。

制限

各アカウントで未完了として保持できる音声文字起こしと翻訳のジョブは、両方を合わせて最大50件です。キュー内、処理中、支払い待ちが対象で、Hosted PBXの録音処理も含みます。この上限またはサービス全体の処理容量に達すると、送信に対して429とtranscription_queue_fullまたはtranslation_queue_fullが返されます。ホストapi.multi.telでは、そのホストへのすべてのリクエストを合算して、クライアントIPアドレスごとに毎分300リクエストの制限もあります。この制限に達すると、JSONのエラー用外側構造ではなく、レート制限ヘッダーとプレーンテキストの本文を伴う429が返されます。

リクエストエラーを処理する

メインホストでは、失敗時にHTTPエラーステータスと、status: "error"、code、message、requestIdを含むJSONが返されます。また、すべてのレスポンスにX-Request-IDヘッダーが含まれます。独自の値を指定することもでき、128文字を超える値は切り詰められます。互換ホストは、response.codeにエラーコードのみを返します。取得可能な場合はリクエストIDとエラーコードを記録し、音声、テキスト、認証情報はログに残さないでください。

主なステータス：

ステータス	意味
400	入力が無効です。
401	認証情報がないか、無効です。
402	前払い残高が不足しています。
403	互換ホストで、これらのサービスを使用できない認証情報です。
404	不明なジョブまたはルートです。
405	サポートされていないメソッド、またはサービス内の不明なパスです。
409	入力の競合、同じ言語への翻訳、または支払い待ちではない音声ジョブの精算です。
413	本文またはファイルが大きすぎます。
422	サポートされていない音声、または利用できない標準翻訳の言語ペアです。
429	キュー、検証、リクエストレートの制限です。
500	読み取れない音声ファイルを含む、予期しないサーバーエラーです。
503	無効または一時的に利用できないサービス、または現在確認できない認証情報です。

検証エラーがすべて同じステータスになると考えず、返されたエラーコードに従ってください。

429または503の場合は、待ち時間を延ばしながら、同じ送信キーで再試行してください。Retry-Afterがある場合は、その指示に従ってください。入力や認証情報が無効な場合は、先に原因を修正してください。以前のジョブがまだキューにある間は、新しいキーを繰り返し送信しないでください。