# Wire formats (/ro/docs/gateway/wire-formats)

Cele trei forme de cerere acceptate de gateway — OpenAI Chat Completions, Anthropic Messages și OpenAI Responses API.

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.

| Format | Endpoint | Potrivit pentru |
| --- | --- | --- |
| OpenAI Chat Completions | `POST /v1/chat/completions` | SDK-urile OpenAI, LangChain, LlamaIndex, Cursor, Continue, majoritatea framework-urilor de agenți. |
| Anthropic Messages | `POST /v1/messages` | SDK-urile Anthropic, Claude Code, orice nativ Anthropic. |
| OpenAI Responses | `POST /v1/responses` | SDK-urile OpenAI mai noi și modul `apiType: "responses"` al Copilot. |

## OpenAI Chat Completions [#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.

<Tabs items={['Cerere', 'Răspuns']}>
<Tab value="Cerere">

```bash
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
  }'
```

</Tab>
<Tab value="Răspuns">

```json
{
  "id": "chatcmpl_7d3c…",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "codai",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Promise.all primește un iterabil de promisiuni și returnează una singură. Se rezolvă cu un array de rezultate odată ce fiecare intrare se rezolvă, păstrând ordinea. Se respinge imediat ce oricare intrare se respinge."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 48,
    "total_tokens": 79,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}
```

</Tab>
</Tabs>

### Tool calling [#tool-calling]

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

```json
{
  "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 [#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 [#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.

<Tabs items={['Cerere', 'Răspuns']}>
<Tab value="Cerere">

```bash
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." }]
  }'
```

</Tab>
<Tab value="Răspuns">

```json
{
  "id": "msg_01Xf…",
  "type": "message",
  "role": "assistant",
  "model": "codai",
  "content": [
    {
      "type": "text",
      "text": "Promise.all primește un iterabil de promisiuni și returnează una singură. Se rezolvă cu un array de rezultate odată ce fiecare intrare se rezolvă, păstrând ordinea. Se respinge imediat ce oricare intrare se respinge."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 31,
    "output_tokens": 48,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}
```

</Tab>
</Tabs>

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 [#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`.

<Tabs items={['Cerere', 'Răspuns']}>
<Tab value="Cerere">

```bash
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" }
  }'
```

</Tab>
<Tab value="Răspuns">

```json
{
  "id": "resp_chatcmpl_7d3c…",
  "object": "response",
  "created_at": 1790000000,
  "status": "completed",
  "model": "codai",
  "output": [
    {
      "type": "message",
      "id": "msg_chatcmpl_7d3c…",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Promise.all primește un iterabil de promisiuni și returnează una singură. Se rezolvă cu un array de rezultate odată ce fiecare intrare se rezolvă, păstrând ordinea. Se respinge imediat ce oricare intrare se respinge.",
          "annotations": []
        }
      ]
    }
  ],
  "output_text": "Promise.all primește un iterabil de promisiuni …",
  "usage": {
    "input_tokens": 31,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 48,
    "total_tokens": 79
  }
}
```

</Tab>
</Tabs>

`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.

<Callout type="warn">
Nesuportat, respins cu `400 bad_request` și un mesaj clar: înlănțuirea `previous_response_id` (trimiți input-ul complet de fiecare dată), `background: true`, uneltele încorporate precum `web_search` și recuperarea răspunsurilor.
</Callout>

## Cum alegi [#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 unelte ș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](./clients.mdx).

Toate trei fac stream — vezi [streaming](./streaming.mdx) pentru formele SSE per format.