Chat Completions

POST https://api-us.tuna.ai/v1/chat/completions sends a conversation to a serverless model and returns the model's next message. It needs an API key. A request that fails returns an error.

Request

The request body is JSON. These are the parameters most apps use:

Parameter	Type	Description
`model`	string	Required. The id of a model from `GET /v1/models`.
`messages`	array	Required. The conversation so far. Each message has a `role` (`system`, `user`, or `assistant`) and `content`.
`max_tokens`	integer	The most tokens the reply can have. Tuna lowers it to the model's own limit if you ask for more.
`temperature`	number	How random the reply is. Lower values give more predictable text.
`top_p`	number	Samples only from the most likely tokens whose probabilities add up to this value.
`stop`	string or array	Text that ends the reply when the model writes it.
`stream`	boolean	Send the reply in pieces as it is generated.
`stream_options`	object	Set `{"include_usage": true}` to get token usage at the end of a stream.
`reasoning_effort`	string	The model's reasoning effort level. Supported levels depend on the model.
`tools`	array	Functions the model can ask your code to run.
`tool_choice`	string or object	Whether the model must, may, or must not call a tool.

More settings, like presence_penalty and frequency_penalty, are in Advanced model control. A message's content can also be a list of text and image parts. See Image input.

Request body

{
  "model": "tuna-us/example-lab/example-model-id",
  "messages": [
    {"role": "system", "content": "You answer in one short sentence."},
    {"role": "user", "content": "Is the tuna one of the fastest sustained swimming fish species? And does it have a streamlined body?"}
  ],
  "max_tokens": 200
}

Response

The response has the same shape as OpenAI's. The reply is in choices[0].message, and usage counts the tokens you are charged for.

Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "tuna-us/example-lab/example-model-id",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Yes. Tuna are among the fastest sustained swimmers, and their bodies are streamlined."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 38, "completion_tokens": 17, "total_tokens": 55, "prompt_tokens_details": {"cached_tokens": 0}}
}

usage.prompt_tokens_details.cached_tokens is how many of the input tokens were billed as cached input. See Input caching.

finish_reason says why the reply ended:

Value	Meaning
`stop`	The model finished on its own, or wrote one of the `stop` strings.
`length`	The reply reached `max_tokens`.
`tool_calls`	The model is asking for tool calls.
`error`	A stream failed after it started. See Errors during a stream.

Streaming

Set stream to true to get the reply as it is generated. The response is a stream of server-sent events, in the same format as OpenAI's. See Streaming for the chunk format, token usage, and errors during a stream.