POST /v1/chat/completions

OpenAI-compatible chat completions with streaming, tools, vision, and model aliases.

No current prepared translation is available. The English source is shown without machine translation.

Request

curl https://api.model-gate.com/v1/chat/completions \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ch-47",
    "messages": [
      {"role": "user", "content": "Explain this API in one sentence."}
    ],
    "stream": false
  }'

The model can be a canonical ID or an enabled alias. Model Gate resolves aliases before pricing and sends the canonical ID upstream.

Response

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "model": "claude-opus-4.7",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Model Gate provides one compatible API for multiple AI models."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 17,
    "total_tokens": 31
  }
}

Streaming request

Set "stream": true. The upstream Server-Sent Events are passed through without rewriting successful event payloads.

Asynchronous request

For supported endpoints, add "async": true with "stream": false. The immediate response is HTTP 202 and contains request_id and a Partner API result URL.

Errors

Provider error details are filtered by the disclosure policy; a safe protocol-compatible message can replace the original body. Locally generated validation errors use the Model Gate error envelope.

Status	Meaning	Action
`400`	Invalid request	Check the request body and model ID.
`401`	Invalid or frozen key	Verify or rotate the API key.
`429`	Rate or concurrency limit exceeded	Respect `Retry-After` and retry with backoff.
`5xx`	Temporary upstream or gateway error	Retry idempotent requests with exponential backoff.

Session ID

Use a stable JSON session_id or X-Session-ID header for every turn of this conversation. Priority is session_id → X-Session-ID → recognized session in metadata.user_id → prompt_cache_key → opening conversation content. The identity layer is independent of provider type. Keeping the same ID does not guarantee a cache hit or disable eligible failover. See conversation identity and sticky routing for automatic fallback, scope, limits and the difference from idempotency and stored context.

The same identity is retained for streaming and for asynchronous submission where this endpoint supports it. Do not send a new paid POST merely to test a session after a timeout; check the existing request first.

An existing recognized metadata session is used without a mismatch error; an ordinary metadata.user_id is preserved, not treated as a conversation. Higher-priority explicit fields win. See the linked identity reference for formats and upstream transport limits.

A recognized metadata session takes precedence over a cache hint. Automatic identity ignores known cache_control decorations and equivalent single-text wrappers without changing the model request. A separately configured, compatible upstream session-header transport does not occupy ordinary metadata.user_id; this capability is configured by the operator, not selected by the client.