Skip to main content

Translation API Reference

The Shisa Translation API translates text between a source and target language with a single multipart/form-data request. This page documents the endpoint, its form fields, the non-streaming response, and the streaming format.

Endpoint​

POST https://api.shisa.ai/translate/

Authenticate with a standard bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY
warning

Translation authenticates with a standard bearer token, the same header every Shisa service uses. A missing or malformed token returns a 401 error. See Authentication for the full conventions.

The request body is multipart/form-data — the fields below are sent as form fields, not JSON.

Request fields​

FieldTypeRequiredDescription
textstringRequiredThe text to translate; maximum 10,000 Unicode codepoints.
source_langstringRequiredSource language code (e.g. ja).
target_langstringRequiredTarget language code (e.g. en).
streamstringOptional"false" (default) for a single JSON response, or "true" for Server-Sent Events.
keywordsrepeated stringOptionalGlossary terms to preserve. Repeat the form field for each term; maximum 20 terms and 100 bytes per term.
contextstringOptionalPrior conversation or other context; maximum 2,000 Unicode codepoints.
modelstringOptionalTranslation model override. Default: shisa-ai/chotto.

Non-streaming response​

With stream=false (the default), the API returns an OpenAI-style JSON object. The translated text is at choices[0].message.content:

{
  "id": "trans_20f537a6-da14-4c98-8ee3-063319c45072",
  "object": "translation.completion",
  "created": 1768299459,
  "model": "shisa-v2.1-unphi4-14b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "お腹が空いた。"
      },
      "finish_reason": "stop"
    }
  ],
  "transcription": "I am hungry",
  "source_lang": "en",
  "target_lang": "ja",
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 8,
    "total_tokens": 55
  }
}
FieldDescription
idUnique identifier for the translation, prefixed with trans_.
objectThe object type. For a non-streaming response this is translation.completion.
createdUnix timestamp (seconds) for when the translation was created.
modelModel ID reported by the backend response. It may differ from the shisa-ai/chotto request alias.
choicesArray of translation choices. Each entry has an index, a message with role and content, and a finish_reason.
choices[0].message.contentThe translated text.
transcriptionThe original source text that was translated.
source_langThe source language code used for the translation.
target_langThe target language code used for the translation.
usageToken accounting: prompt_tokens, completion_tokens, and total_tokens.

Streaming response​

Set stream=true to receive the translation as Server-Sent Events for real-time delivery:

curl -X POST "https://api.shisa.ai/translate/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "text=I am hungry" \
  -F "source_lang=en" \
  -F "target_lang=ja" \
  -F "stream=true"

Each chunk is a data: event whose object is translation.completion.chunk, carrying text (which may be an empty string) at choices[0].delta.content. All chunks for one request use the same id. The first chunk also includes transcription, source_lang, and target_lang. A chunk includes usage when the backend supplies it, followed by a data: [DONE] terminator. Streaming chunks do not include finish_reason:

data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "transcription": "I am hungry", "source_lang": "en", "target_lang": "ja", "choices": [{"delta": {"content": ""}, "index": 0}]}
data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "お"}, "index": 0}]}
data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "腹が"}, "index": 0}]}
data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "空いた"}, "index": 0}]}
data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "。"}, "index": 0}]}
data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": ""}, "index": 0}], "usage": {"prompt_tokens": 47, "completion_tokens": 8, "total_tokens": 55}}
data: [DONE]

Next steps​