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

Field	Type	Required	Description
text	string	Required	The text to translate.
source_lang	string	Required	Source language code (e.g. ja).
target_lang	string	Required	Target language code (e.g. en).
stream	string	Optional	"false" (default) for a single JSON response, or "true" for Server-Sent Events.

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-ai/chotto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "お腹が空いた。"
      },
      "finish_reason": "stop"
    }
  ],
  "transcription": "I am hungry",
  "source_lang": "en",
  "target_lang": "ja",
  "balance": {
    "free": 1000,
    "premium": 0
  },
  "usage": {
    "prompt_tokens": 3,
    "completion_tokens": 1,
    "total_tokens": 4
  }
}

Field	Description
id	Unique identifier for the translation, prefixed with trans_.
object	The object type. For a non-streaming response this is translation.completion.
created	Unix timestamp (seconds) for when the translation was created.
model	The model that produced the translation — shisa-ai/chotto.
choices	Array of translation choices. Each entry has an index, a message with role and content, and a finish_reason.
choices[0].message.content	The translated text.
transcription	The original source text that was translated.
source_lang	The source language code used for the translation.
target_lang	The target language code used for the translation.
balance	Your remaining credit balance, with free and premium token counts.
usage	Token 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 the partial text at choices[0].delta.content. A final chunk sets finish_reason to "stop" and includes usage, followed by a data: [DONE] terminator:

data: {"id": "trans_446d7397-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": ""}, "index": 0}]}
data: {"id": "trans_fe190f5d-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "お"}, "index": 0}]}
data: {"id": "trans_71bbdcec-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "腹が"}, "index": 0}]}
data: {"id": "trans_7c2d47d7-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "空いた"}, "index": 0}]}
data: {"id": "trans_99e10e01-...", "object": "translation.completion.chunk", "choices": [{"delta": {"content": "。"}, "index": 0}]}
data: {"id": "trans_0a0396bd-...", "choices": [{"delta": {}, "index": 0, "finish_reason": "stop"}], "usage": {...}}
data: [DONE]

Next steps

• Make a working request in the Quickstart.
• Learn the auth header conventions across services in Authentication.
• See how usage is billed on Pricing.