Chat Completions API

Access state-of-the-art language models through an interface that is fully compatible with the OpenAI Chat Completions specification. Multimodal input, media-intent detection, and integrated ACS content-safety screening are supported out of the box.

Authentication

All API requests require a Bearer token in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Available Models

The following models are available through the API. Prices are per 1 million tokens and already include the account markup.

Chat Completions

POST/api/v1/chat/completions

Generates chat completions from a conversation history. Accepts a list of messages and returns the model's response.

Request

Required parameters

Message object

{
  "role": "user",        // "system", "user", or "assistant"
  "content": "Hello!"    // string or array (for multimodal)
}

Optional parameters

Example request

{
  "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
}

Response

{
  "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

When stream is true, the API returns Server-Sent Events. Each event is a JSON object prefixed with data: , 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

When detect_media is true, a secondary model call analyzes the conversation to determine whether the assistant agreed to generate media. Combine it with a system prompt that instructs the model how to handle media requests.

You are allowed to send pictures if asked. Avoid describing the image, just act as you sent it, the system will add the right image automatically.

Supported media types

Response with media object

{
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "Here's a beautiful sunset scene." }, "finish_reason": "stop" }
  ],
  "media": {
    "image": "A breathtaking sunset over a calm ocean, vibrant orange and pink hues reflecting on the water, photorealistic, cinematic composition"
  }
}

Multimodal Support

Many models support image inputs alongside text. Use an array for the message content:

{
  "model": "google/gemini-flash-1.5",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's in this image?" },
        { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } }
      ]
    }
  ]
}

Base64 data URIs are also supported:

{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." } }

Advanced Parameters

Additional model- or provider-specific parameters are passed through to the underlying model.

Provider routing

{
  "model": "google/gemini-2.5-flash",
  "messages": [],
  "provider": { "order": ["Anthropic", "OpenAI"], "allow_fallbacks": false }
}

Additional model parameters

• repetition_penalty — penalize repeated sequences
• top_k — limit sampling to top K tokens
• min_p — minimum probability threshold
• top_a — alternative top-p sampling

{
  "model": "google/gemini-flash-1.5",
  "messages": [],
  "temperature": 0.8,
  "top_k": 40,
  "repetition_penalty": 1.1
}

Compliance & Rulesets

Every request is screened by the ACS (Automated Content Safety) service before a response is released. Non-streaming requests run a fast pre-LLM deterrent check plus a post-LLM authoritative check; streaming requests run a single authoritative check before streaming begins. When content is blocked, the API returns a normal completion whose finish_reason is content_filter plus a top-level filter_categories array.

Selecting a ruleset

ACS rulesets define the set of categories applied to a review. Pass compliance_ruleset to target a non-default ruleset for the request:

{
  "model": "google/gemini-2.5-flash",
  "messages": [{ "role": "user", "content": "…" }],
  "compliance_ruleset": "strict"
}

• If compliance_ruleset is omitted, empty, or whitespace-only, the API sends "default" to ACS.
• The selected ruleset applies to every compliance check performed for that request.

Pre-compliance signal

Many clients run an upstream pre-compliance system on the raw prompt. The precompliance parameter forwards that system's output to ACS so it is included as additional context in the review.

• Non-authoritative: ACS still makes the final decision — the signal is one input among others.
• Truncated: values longer than 2000 characters are truncated.

{
  "model": "google/gemini-2.5-flash",
  "messages": [{ "role": "user", "content": "…" }],
  "precompliance": "no banned tokens matched; risk_score=0.04"
}

Bypass flags

Error Handling

Errors return an appropriate HTTP status and a JSON error object:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": null
  }
}

Code Examples

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://chat.api.efficientstack.com/api/v1"
)

response = client.chat.completions.create(
    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,
    extra_body={"compliance_ruleset": "default", "precompliance": "risk_score=0.04"}
)

print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://chat.api.efficientstack.com/api/v1'
});

const completion = await openai.chat.completions.create({
  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: 'risk_score=0.04'
});

console.log(completion.choices[0].message.content);

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": "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"
  }'

<?php
require 'vendor/autoload.php';

use OpenAI;

$client = OpenAI::factory()
    ->withApiKey('YOUR_API_KEY')
    ->withBaseUri('https://chat.api.efficientstack.com/api/v1')
    ->make();

$response = $client->chat()->create([
    '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'
]);

echo $response->choices[0]->message->content;
?>