Wire formats

Alegi formatul pe care clientul tău îl vorbește deja. Toate trei acceptă aceeași cheie bearer, rezolvă aceleași alias-uri, aplică aceleași limite și scriu aceleași înregistrări de usage. Nimic din contul tău nu depinde de care dintre ele alegi.

OpenAI Chat Completions

Forma nativă a gateway-ului. Acceptă model, messages, stream, max_tokens (sau max_completion_tokens), temperature, top_p, stop, tools, tool_choice, response_format, reasoning_effort și user. Câmpurile necunoscute trec mai departe către upstream.

curl https://ai.codai.ro/v1/chat/completions \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codai",
    "messages": [
      { "role": "system", "content": "Ești un inginer senior concis." },
      { "role": "user", "content": "Explică Promise.all în trei propoziții." }
    ],
    "max_tokens": 300
  }'

Tool calling

Tool-uri OpenAI standard de tip funcție. Când trimiți tools, gateway-ul te tratează ca proprietar al buclei de tool-uri: îți trimite înapoi tool_calls neatinse și nu pornește niciodată o a doua buclă de agent în spatele tău.

{
  "model": "codai",
  "messages": [{ "role": "user", "content": "Cum e vremea la Cluj?" }],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Vremea curentă pentru un oraș",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ]
}

Răspunsul poartă choices[0].message.tool_calls și finish_reason: "tool_calls". Trimiți rezultatul înapoi ca mesaj { "role": "tool", "tool_call_id": "…", "content": "…" }.

Imagini

Trimiți părți de conținut image_url pe un mesaj de utilizator, exact ca la OpenAI. codai anunță vision: true.

Anthropic Messages

Acceptă forma publică Anthropic Messages: model, messages cu conținut pe blocuri, system, max_tokens (obligatoriu), temperature, top_p, top_k, stop_sequences, stream, tools, tool_choice, metadata. Autentificarea este Authorization: Bearer sau x-api-key — ambele funcționează. Trimiți anthropic-version: 2023-06-01 ca la upstream.

curl https://ai.codai.ro/v1/messages \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codai",
    "max_tokens": 1024,
    "system": "Ești un inginer senior concis.",
    "messages": [{ "role": "user", "content": "Explică Promise.all în trei propoziții." }]
  }'

Când upstream-ul rezolvat este nativ Anthropic, byte-ii sunt trimiși mai departe 1:1 — cel mai mic timp posibil până la primul token. Când este de formă OpenAI (Gemini, de exemplu) gateway-ul traduce din zbor; forma răspunsului pe care o vezi este mereu Anthropic.

OpenAI Responses API

Un strat de traducere peste Chat Completions: cererea este mapată la o cerere de chat, reintră în aceeași rută în proces (așa că autentificarea, limitele, rutarea, caching-ul și usage se aplică neschimbate), iar rezultatul este mapat înapoi. Suportat: input ca string sau array de elemente { role, content }, elemente function_call / function_call_output pentru bucle de agent, instructions, tools (tip funcție), tool_choice, max_output_tokens, temperature, top_p, stream și reasoning.effort.

curl https://ai.codai.ro/v1/responses \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "codai",
    "instructions": "Ești un inginer senior concis.",
    "input": "Explică Promise.all în trei propoziții.",
    "reasoning": { "effort": "high" }
  }'

reasoning.effort urmează vocabularul OpenAI și se mapează pe tier-urile codai: xhigh → max, none → minimal; valorile necunoscute sunt eliminate. Un header X-Codai-Effort câștigă peste body.

Cum alegi

• Ai deja cod? Păstrezi formatul lui. Nu există diferență de capabilități pentru chat.
• Pornești de la zero? Chat Completions are cel mai larg suport de tool-uri și este forma nativă a gateway-ului.
• Ai nevoie de conținut pe blocuri în stil Claude sau autentificare x-api-key? Messages.
• Copilot în modul Responses? Responses — vezi clienți.

Toate trei fac stream — vezi streaming pentru formele SSE per format.