API за превођење текста

Овај API преводи текст као задатке у реду за обраду, са једним циљним језиком по задатку. Пошаљите текст, сачувајте враћени ID задатка и преузимајте задатак док се обрада не заврши. Сваки захтев шаљите преко HTTPS-а са акредитивима свог налога, било HTTP Basic акредитивима као у примерима или API токеном, као што је описано у одељку Аутентификација. Акредитиве чувајте на свом серверу.

Крајње тачке

Два API сервера, https://api.multi.tel и сервер за компатибилност https://api.multitel.net, деле исте задатке, кључеве идемпотентности, ограничења и наплату у оквиру налога. Разликују се по омотачу одговора, па доследно користите један сервер са одговарајућим парсером.

На серверу api.multi.tel свака путања је доступна и са префиксом /v1/translate уместо /v3/translate. На серверу api.multitel.net користите путање /v3/translate.

Одговор са информацијама о услузи садржи enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages и ratesNanosPerCharacter. cpuLanguages наводи кодове основних језика који се прихватају за стандардни превод. ratesNanosPerCharacter даје подешену цену по кодној тачки изворног текста за сваки механизам, у милијардитим деловима америчког долара: вредност 5000 значи $5 по милиону кодних тачака. Одговор не наводи да ли је побољшани превод тренутно доступан; процена за побољшани превод враћа 503 када није доступан. Читање је бесплатно.

Преведите текст

Пошаљите JSON са Content-Type: application/json на POST https://api.multi.tel/v3/translate. Сваки задатак има један циљни језик, па пошаљите засебан задатак за сваки циљни језик.

Језичко-регионални кодови су BCP 47 ознаке дужине од 2 до 63 знака, састављене од слова, цифара и цртица. Они се канонизују, па се en-us бележи као en-US. Неисправне ознаке, као и und, mul или zxx, враћају 400 invalid_translation_language. Доступност стандардног превода проверава се према основном језику, а nb и nn се рачунају као no. Регионални циљни код као што је fr-CA се прихвата и бележи, али стандардни резултат прати основни језик и није гарантовано да ће одражавати регион.

На овом серверу ограничите тело захтева на 128 KiB. Шаљите текст као UTF-8 уместо да сваки знак ван ASCII скупа представите као \u секвенцу, што захтев са 20,000 знакова може да доведе преко ограничења.

Тело прихвата само ова четири поља. Свако друго својство одбија се са 400 invalid_translation_request, укључујући idempotency_key, ID-јеве власника, ознаке за бесплатну обраду и низове сегмената.

Идемпотентност и поновна употреба

Свако слање захтева заглавље Idempotency-Key дужине од 1 до 190 знакова. Користите ASCII слова, цифре, -, _, . и :, без размака на почетку или крају; недостајући кључ или кључ од 191 или више знакова одбија се са 400. Кључеви важе у оквиру вашег налога и услуге превођења, на оба сервера и за све акредитиве вашег налога.

• Исти кључ са истим текстом, канонизованим језицима и механизмом враћа постојећи задатак са HTTP 200 и duplicate: true, без нове наплате.
• Исти кључ са другачијим текстом, језицима или механизмом враћа 409 idempotency_conflict. Исти кључ враћа 409 и ако се верзија обраде променила од креирања његовог задатка. У том случају прочитајте оригинални задатак по његовом ID-ју уместо да га поново шаљете.
• Нови кључ са истим текстом, канонизованим језицима и механизмом враћа постојећи задатак са HTTP 200 и duplicate: true, без нове наплате обраде, ако је задатак са тим садржајем и тренутном верзијом обраде у реду за обраду, у извршавању, завршен или чека плаћање. Поново употребљен задатак који чека плаћање и даље захтева измирење. Неуспешни задаци се не користе поново: креира се нови задатак који се наплаћује када се заврши.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Нови задатак враћа HTTP 202. Пример текста има 57 кодних тачака, па по цени од $5 по милиону кодних тачака кошта $0.000285. Скраћен одговор (идентификатор је пример):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Слање може да врати и 402 insufficient_balance када припејд стање не може да покрије задатак заједно са осталим незавршеним задацима и 429 translation_queue_full када ваш налог или услуга има превише незавршених задатака. Враћа 503 у следећим случајевима:

• paid_translation_not_enabled док је плаћени превод онемогућен.
• translation_unavailable за захтев за побољшани превод док побољшани превод није доступан.
• translation_pricing_unavailable док изабрани механизам нема подешену тарифу.

Поновите захтеве са одговорима 429 и 503 касније са истим кључем.

Изаберите квалитет

Дуг текст се обрађује у мањим деловима и поново спаја. Преломи редова и размаци могу се променити, а реченица може изгубити контекст на граници између делова обраде. Сачувајте оригинални текст и прегледајте спојени резултат. Стандардни превод користи основни језик регионалне ознаке; прихватање и бележење ознаке не гарантују регионалне формулације.

Стандардни превод се извршава у CPU радним процесима. Побољшани превод шаље текст подешеној спољној AI услузи. Његов резултат и даље захтева преглед; услуга не гарантује да је један механизам тачнији за сваки језички пар или врсту текста.

Стандардни превод је нацрт чији квалитет и време обраде варирају у зависности од језичког пара. Побољшани превод је намењен тексту у ком је контекст важан, али и даље захтева проверу важних имена, бројева, негација и обавеза. Ниједна опција не исправља грешке које су већ присутне у оригиналном транскрипту, па сачувајте оригинал ради поређења.

Користите GET /v3/translate на истом API серверу да бисте проверили тренутну доступност, подржане језике за стандардни превод и подешене тарифе. Стандардни захтев чији изворни или циљни основни језик није у cpuLanguages враћа 422 translation_language_pair_unavailable. Када је source_language наведен и има исти основни језик као циљни језик, захтев враћа 409 translation_same_language уместо да креира задатак. Побољшани превод се омогућава засебно: док је недоступан, слање задатака и процене за побољшани превод враћају 503.

Најпре направите процену

На серверу api.multi.tel пошаљите исто JSON тело на POST /v3/translate/estimate. Кључ идемпотентности није потребан. Процена примењује исту валидацију, укључујући провере за 422 и 409, али не креира задатак, не преводи текст, не резервише средства, не проверава ваше стање и не терети ваш налог. Враћа HTTP 200 са estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd и costUsd у оквиру data. За горњи пример, costUsd је 0.000285000 по стандардној тарифи. Док побољшани превод није доступан, процена за побољшани превод враћа 503 service_unavailable. Процене користе тренутно подешену тарифу. Тарифа задатка се фиксира при креирању задатка и његова наплата користи ту тарифу.

Преузмите превод

Ново слање враћа HTTP 202, а постојећи или поново употребљен задатак враћа HTTP 200. Сачувајте data.id и користите заједнички ток рада са задацима. Објекат задатка садржи ова поља:

• id, status, engine, sourceLocale и targetLocale.
• sourceCharacters, costUsd, costIsEstimate и pricePerMillionCharactersUsd.
• progress и createdAt.
• modelVersion, непрозиран стринг верзије обраде.
• duplicate у одговорима за поново употребљене задатке.
• failureCode за неуспешне задатке: translation_failed, translation_timeout, input_failed или worker_lease_lost.

Неуспешан задатак приказује costUsd са вредношћу нула.

Завршен задатак има data.result са sourceLocale (празно ако није наведен изворни језик), targetLocale, преведеним пољем text (текстови сегмената спојени преломима редова) и segments. За текст послат преко овог API-ја, segments садржи један унос са преведеним пољем text и циљним пољем language. Резултати задатака који чекају плаћање задржавају се до измирења.

Коришћење api.multitel.net

Крајња тачка за компатибилност POST https://api.multitel.net/v3/translate прихвата иста JSON поља и исто заглавље Idempotency-Key. Ако заглавље недостаје, прихвата и стринг idempotency_key у JSON телу. Свако друго додатно поље одбија се са 400 unsupported_translation_option. На овом серверу необрађено тело може имати до 256,000 бајтова, а текст са више од 20,000 кодних тачака враћа 413 translation_too_large уместо 400. Празно поље source_language третира се као изостављено. Одговор 429 укључује Retry-After: 15. Овај сервер враћа и следеће грешке:

• 400 json_body_required када тело недостаје, није исправан JSON или је JSON скаларна вредност. Пошаљите JSON објекат.
• 400 invalid_translation_options када text, target_language или engine недостаје, празно је или није стринг, или source_language није стринг.
• 400 invalid_translation_text за текст који садржи само беле знакове.
• 400 invalid_translation_engine за непознат механизам.
• 400 idempotency_key_required за недостајући, празан или предугачак кључ, или за idempotency_key који није стринг.
• 400 invalid_job за неисправно форматиран ID задатка.

Одговори услуге превођења са овог сервера користе омотач {"status":{"code":HTTP_STATUS},"response":{...}}, где је status објекат. Прочитајте ID задатка из response.id и завршени резултат из response.result. Код грешке се налази у response.code, без поруке или ID-ја захтева. Неуспешну аутентификацију (401) враћа општа провера пријављивања сервера и тело одговора може бити другачије, па проверите HTTP статус пре парсирања. Задаци се деле са примарним сервером, али користите исти сервер за периодично преузимање, измирење и потрошњу како би ваш парсер одговарао омотачу. Овај сервер прихвата иста JSON поља и на /v3/translate/estimate без кључа идемпотентности, а процена је у оквиру response.