# Chat Completions API
  
  > OpenAI-compatible chat completions with multimodal input, media-intent
  > detection, and integrated ACS (Automated Content Safety) compliance
  > screening (ruleset selection + upstream pre-compliance signal forwarding).
  
  Base URL: https://chat.api.efficientstack.com/api/v1
  Human docs: https://chat.api.efficientstack.com/
  Playground: https://chat.api.efficientstack.com/playground/
  
  ## Authentication
  
  All requests require a Bearer token in the `Authorization` header:
  
  ```
  Authorization: Bearer YOUR_API_KEY
  ```
  
  ## Endpoints
  
  - `GET  /api/v1/models` — list available models (no auth required). Free
    models and `openrouter/*` routing pseudo-models are excluded; prices are
    returned with the account markup already applied.
  - `POST /api/v1/chat/completions` — create a chat completion.
  
  ## POST /api/v1/chat/completions
  
  ### Required parameters
  
  - `model` (string): model ID from `GET /api/v1/models`.
  - `messages` (array): conversation history. Each item has `role`
    ("system" | "user" | "assistant") and `content` (string, or an array of
    content parts for multimodal input).
  
  ### Optional parameters
  
  - `temperature` (float, default 0.7): sampling temperature, 0.0–2.0.
  - `max_tokens` (integer): max tokens to generate.
  - `top_p` (float): nucleus sampling, 0.0–1.0.
  - `top_k` (integer): top-K sampling.
  - `frequency_penalty` (float): -2.0–2.0.
  - `presence_penalty` (float): -2.0–2.0.
  - `repetition_penalty` (float): penalize repeated sequences.
  - `stop` (string | array): stop sequence(s).
  - `stream` (boolean, default false): stream Server-Sent Events. Cannot be
    combined with `detect_media`.
  - `detect_media` (boolean, default false): analyze the conversation for
    media-generation intent. Non-streaming only.
  - `provider` (object): provider routing hints, e.g.
    `{"order":["Anthropic","OpenAI"],"allow_fallbacks":false}`.
  - `timeout` (integer seconds): upstream request timeout (capped by server max).
  
  ### Compliance parameters (ACS)
  
  Every request is screened by the ACS compliance service unless bypassed.
  Non-streaming requests run a fast pre-LLM deterrent check (fail-open) plus a
  post-LLM authoritative check (fail-closed). Streaming requests run a single
  authoritative pre-stream check (fail-closed).
  
  - `bypass_compliance` (boolean, default false): skip both input and output
    compliance checks.
  - `bypass_compliance_in` (boolean, default false): skip only the input check.
  - `bypass_compliance_out` (boolean, default false): skip only the output check.
  - `compliance_ruleset` (string, default "default"): ACS ruleset ID to
    evaluate the content against. If omitted, empty, or whitespace-only,
    "default" is sent to ACS.
  - `precompliance` (string, optional): verbatim output of an upstream
    pre-compliance system, forwarded to ACS as additional, NON-AUTHORITATIVE
    review context. ACS still makes the final decision. Truncated to 2000
    characters. Forward the raw signal (scores, versions, matched keywords)
    rather than a boolean — more detail is better.
  
  When content is blocked, the API returns a normal completion object whose
  `choices[0].finish_reason` is `"content_filter"`, a refusal message, and a
  top-level `filter_categories` array of flagged ACS category IDs.
  
  ### Message content parts (multimodal)
  
  Text:
  ```json
  { "type": "text", "text": "What's in this image?" }
  ```
  
  Image (URL or base64 data URI):
  ```json
  { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
  ```
  
  ### Example request
  
  ```json
  {
    "model": "google/gemini-2.5-flash",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is the capital of France?" }
    ],
    "temperature": 0.7,
    "max_tokens": 150,
    "compliance_ruleset": "default",
    "precompliance": "no banned tokens matched; risk_score=0.04"
  }
  ```
  
  ### Example response
  
  ```json
  {
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1699200000,
    "model": "google/gemini-2.5-flash",
    "choices": [
      {
        "index": 0,
        "message": { "role": "assistant", "content": "The capital of France is Paris." },
        "finish_reason": "stop"
      }
    ],
    "usage": { "prompt_tokens": 20, "completion_tokens": 8, "total_tokens": 28 }
  }
  ```
  
  ### Streaming
  
  Set `stream: true`. The response is `text/event-stream`; each event is a
  `data: {json}` line and the stream ends with `data: [DONE]`.
  
  ```
  data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"The"},"finish_reason":null}]}
  
  data: [DONE]
  ```
  
  ### Media detection
  
  With `detect_media: true` (non-streaming only), a secondary model call decides
  whether the assistant agreed to produce media. When detected, the response adds
  a top-level `media` object:
  
  ```json
  {
    "media": {
      "image": "A breathtaking sunset over a calm ocean, vibrant orange and pink hues, photorealistic, cinematic"
    }
  }
  ```
  
  Supported media keys: `image`, `video`, `voice`, `music`. Use the returned
  prompt with your own downstream generation service.
  
  ## Errors
  
  Errors use the OpenAI shape:
  
  ```json
  { "error": { "message": "Invalid API key provided", "type": "invalid_request_error", "code": null } }
  ```
  
  | Status | Meaning |
  | --- | --- |
  | 400 | Invalid request format or parameters |
  | 401 | Missing or invalid API key |
  | 402 | Insufficient balance |
  | 429 | Rate limited |
  | 500 | Internal server error |
  | 502 | Upstream error |
  | 503 | Model temporarily unavailable |
  | 504 | Upstream timeout |
  
  ## Quick start (curl)
  
  ```bash
  curl -X POST "https://chat.api.efficientstack.com/api/v1/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-2.5-flash",
      "messages": [{"role": "user", "content": "Hello!"}],
      "compliance_ruleset": "default"
    }'
  ```