Chat completions

The API answers chat completions from your organization's published models, in OpenAI's format. For a first request, see the API quickstart.

Both live under the address on the API screen, which ends in /v1.

Authentication

Send your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

A key reaches only its organization's published models, and only those it may call. A missing, revoked or expired key gets 401 invalid_api_key.

The request

curl https://YOUR_API_ADDRESS/v1/chat/completions \
  -H "Authorization: Bearer $TUNE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "system", "content": "Answer in one sentence."},
      {"role": "user", "content": "What is a LoRA adapter?"}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'

A field set to null counts as not sent.

Fields

Send whole numbers as integers: 100.0 is refused for max_tokens.

Fields that are refused

Any other field gets 400 unsupported_parameter, naming it, so you never assume something was applied when it was not. This includes OpenAI's tools, tool_choice, functions, response_format, logprobs, logit_bias, presence_penalty and frequency_penalty. Remove the field and send again.

Messages

Each message has exactly two fields:

• role: system, user or assistant.
• content: a string, or a list of parts:
  • {"type": "text", "text": "..."} in any message.
  • {"type": "image_url", "image_url": {"url": "..."}} in user messages, for a vision model. See Images.

A name field, a tool or developer role, or an empty list is refused with 400 invalid_request.

The conversation, its images and max_tokens together must fit the model's context length. If they do not, you get 400 model_refused.

Images

A published vision model reads images in user messages. Send each image as an image_url part:

{"role": "user", "content": [
  {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}},
  {"type": "text", "text": "What does this chart show?"}
]}

• A link must start with https:// and be at most 2,048 characters, with no spaces. It must be reachable from the internet. The image may be up to 20 MB and must download within 10 seconds.
• Inline data is a base64 data URL of a PNG, JPEG, WebP or GIF, such as data:image/jpeg;base64,.... Use the file's real type.
• At most 4 images per request, counting every message.
• detail inside image_url is accepted and ignored.

Images are not stored. Each image uses tokens of the context length: see Images and the context length. A text model refuses images with 400 model_text_only. Images need the Pro plan: on Free and Starter they are refused with 403 plan_upgrade_required, and text to the same model is answered.

Request size

Base64 makes an image about a third larger. Your organization can send 2 requests over 2 MiB at a time; more get 429 with Retry-After: 1. Images sent as links keep requests small.

Send an image with Python

import base64
import os

from openai import OpenAI

client = OpenAI(base_url="https://YOUR_API_ADDRESS/v1", api_key=os.environ["TUNE_API_KEY"])

with open("receipt.jpg", "rb") as file:
    image = base64.b64encode(file.read()).decode()

answer = client.chat.completions.create(
    model="your-model-name",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image}"}},
            {"type": "text", "text": "What is the total on this receipt?"},
        ],
    }],
    max_tokens=300,
)
print(answer.choices[0].message.content)

For a link, put the https:// address in url instead.

The response

{
  "id": "chatcmpl-8f2c1a9e4b7d40a1",
  "object": "chat.completion",
  "created": 1791158400,
  "model": "your-model-name",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "A LoRA adapter is a small set of weights trained on top of a base model."},
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 31, "completion_tokens": 17, "total_tokens": 48}
}

• model is the published name you sent.
• choices holds one choice. finish_reason is stop, or length when the answer reached max_tokens.
• usage holds the token counts, or null if the model reported none.
• logprobs is always null. Only OpenAI's fields are returned.

Streaming

With "stream": true, the answer comes as server-sent events. Each event is data: and a JSON chunk; the last is data: [DONE].

data: {"id":"chatcmpl-8f2c1a9e4b7d40a1","object":"chat.completion.chunk","created":1791158400,"model":"your-model-name","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-8f2c1a9e4b7d40a1","object":"chat.completion.chunk","created":1791158400,"model":"your-model-name","choices":[{"index":0,"delta":{"content":"A LoRA adapter is a small set of weights."},"logprobs":null,"finish_reason":"stop"}]}

data: [DONE]

• Each chunk's delta.content holds the next piece of the answer.
• With "stream_options": {"include_usage": true}, one more chunk comes before [DONE], with empty choices and the usage.
• Errors found before the answer starts come as normal JSON errors.
• A stream that stops without data: [DONE] is incomplete: it hit a limit or the model failed. Retry it, or shorten the answer.

List models

curl https://YOUR_API_ADDRESS/v1/models -H "Authorization: Bearer $TUNE_API_KEY"

{"object": "list", "data": [{"id": "your-model-name", "object": "model", "created": 1791158400, "owned_by": "organization"}]}

data lists every published model the key may call, stopped ones included. created is when it was published. Listing counts toward the key's requests per minute and the organization's.

Cold starts and retries

A wake-on-request model that is asleep starts when a request arrives. The API holds your request for up to a minute while it starts. If it is still not ready, you get 503 model_starting with Retry-After: 15. An always-on model that is starting answers 503 model_starting at once, with Retry-After: 30.

Limits

A stream holds one of the key's Requests at once, and one of the organization's, until it ends.

Errors

Every error has this shape:

{"error": {"message": "max_tokens must be a whole number from 1 to 8192", "type": "invalid_request_error", "code": "invalid_request"}}

Act on code. The message says what was wrong.

400 Bad request

Type invalid_request_error.

401, 403, 404, 405, 408 and 413

429 Too many requests

Each has a Retry-After header with the seconds to wait.

The type is insufficient_quota for quota_exceeded and rate_limit_error for the others.

500, 502 and 503

The type is api_error for 500 and 502, and service_unavailable for 503.