语音和翻译任务

将下方的 SERVICE 替换为 speech_to_text 或 translate，将 JOB_ID 替换为返回的 UUID。所有操作均需要使用您账号的凭证，详见身份验证，且仅限于所属账号。您可以从任一 API 服务器读取任务，但各服务器使用的响应外层结构不同，因此请始终使用同一个服务器。

在 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 字段，以确定处理是否结束。

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 是 UTC 日期，格式为 YYYY-MM-DD，且包含起止两天。省略时，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 个请求，合并计算发送到该服务器的所有请求。触发此限制时会返回 429，附带速率限制响应头和纯文本响应体，而不是 JSON 错误外层结构。

处理请求错误

在主服务器上，失败时会返回 HTTP 错误状态以及包含 status: "error"、code、message 和 requestId 的 JSON。每个响应还包含 X-Request-ID 响应头。您可以自行提供值；超过 128 个字符的值会被截断。兼容服务器仅在 response.code 中返回错误代码。请记录可用的请求 ID 和错误代码，不要将音频、文本或凭证写入日志。

常见状态：

请根据返回的错误代码处理，不要假定所有验证失败都会使用同一状态。

遇到 429 或 503 时，请等待后使用相同的提交键重试，并逐步延长等待时间；如有 Retry-After，请遵循该响应头。对于无效输入或凭证，请先修正原因。先前任务仍在排队时，不要反复提交新键。