Tarseek API · Pre-production

Chat / text generation

POSThttps://tarseek.com/v1/chat/completions

This is the text generation API. Not every catalog model is a chat model.

Minimal request

completion = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Be brief."},
        {"role": "user", "content": "What is Tarseek?"},
    ],
)

Messages and roles

Roles: system, developer, user, assistant, tool. Content may be a string or an array of parts (text + image_url / input_image for vision, or input_file with a Tarseek file_id).

Safety identifiers

Applications with end users should send a stable, pseudonymous safety_identifier on every request. Use an internal identifier or a one-way hash—never an email address, name, or other personal data. Tarseek stores only a keyed hash for abuse correlation and translates the value to the provider's supported safety/user metadata field.

File inputs

Upload reusable private inputs with multipart POST /v1/files, wait for status: ready, then reference the returned ID as {"type":"input_file","file_id":"file_..."}. Send an Idempotency-Key when uploading so a safe retry returns the original file instead of creating a duplicate. Retry network errors, HTTP 429, and HTTP 5xx with exponential backoff; do not retry validation errors. List, inspect, and delete files with GET /v1/files, GET /v1/files/{file_id}, and DELETE /v1/files/{file_id}. Generated images are returned as private output-file objects and can be downloaded from /v1/files/{file_id}/content. Reusable API files expire after 30 days by default; expires_in_seconds can select 1 hour–30 days.

Chat and generation currently support text and image capabilities only. Audio and video models remain unavailable.

A tool message requires tool_call_id. Only assistant messages may contain tool_calls, and only assistant tool-call messages may omit content.

Max output

Use max_completion_tokens. The deprecated max_tokens field remains accepted for compatible legacy models. Sending both is a validation error. The catalog’ssupported_parameters field tells you which form a model accepts.

Sampling

temperature (0–2) and top_p (0–1] are accepted. top_k, frequency/presence/repetition penalties are not Tarseek-normalized yet — see Parameters.

Stop and seed

stop is one string or 1–4 strings. seed is accepted on the schema only for models and deployments that advertise support. Unsupported optional parameters fail before routing with 400 unsupported_parameter.

Response

Every successful non-streaming response has an OpenAI-shaped id, object: "chat.completion", created, canonical model, andchoices. Provider-private fields and upstream identifiers are not exposed. Normalized usage is included when the provider reports it.