AI Service V1

AI Service V1 is an OpenAI-compatible proxy for major cloud LLM providers. You send chat completions in the standard messages format; we forward the request to the provider, log token usage, and deduct cost from your API balance.

Base URL. https://api.koveh.com/ai/

Provider-specific paths are listed below. The legacy unified path https://api.koveh.com/ai/v1/ still works and routes to the OpenAI implementation.

Authentication

All requests require the X-API-Key header (not Bearer). Request an API key via API Access & Authentication.

X-API-Key: YOUR_API_KEY

How Koveh uses these models

Across koveh.com and internal automations we default to the GPT-5.4 family on the OpenAI path unless a task needs another provider.

Legacy OpenAI ids such as gpt-4o and gpt-4o-mini still work on the wire, but we recommend passing gpt-5.4-* explicitly in new integrations. On koveh.com, older ids are remapped internally (for example gpt-4o → gpt-5.4-mini).

For self-hosted text generation and embeddings on our infrastructure, see Qwen3 AI API — it is a separate service, not part of AI Service V1.

Supported providers

Each provider has its own path prefix. The request body follows the OpenAI Chat Completions shape unless noted.

The gateway does not hard-limit model names: any id accepted by the upstream provider can be sent in the model field. Costs are calculated from actual token usage for that model.

Quick start

Non-streaming chat (OpenAI path, recommended model):

curl -s https://api.koveh.com/ai/openai/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Summarize what a data warehouse staging layer does in two sentences."}
    ],
    "stream": false
  }'

Streaming — set "stream": true. The response is Server-Sent Events with data: {"content": "..."} chunks and a final data: [DONE].

Claude example — same JSON shape; use /ai/claude/chat/completions and a Claude model id:

curl -s https://api.koveh.com/ai/claude/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Endpoints

1. Chat completion (per provider)

POST <provider-path>/chat/completions

Examples:

• POST https://api.koveh.com/ai/openai/chat/completions
• POST https://api.koveh.com/ai/claude/chat/completions
• POST https://api.koveh.com/ai/deepseek/chat/completions

Request body (OpenAI-compatible):

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "system", "content": "Optional system prompt"},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "max_tokens": 1024,
  "temperature": 0.7
}

Additional OpenAI parameters supported by the upstream API (for example response_format, reasoning_effort on GPT-5.4-class models) are forwarded as-is when the provider accepts them.

Response. Standard OpenAI-style chat.completion object with choices, usage (prompt / completion / total tokens), and the resolved model name.

2. Unified completion (legacy)

POST https://api.koveh.com/ai/v1/chat/completions

Proxies to the OpenAI implementation for backward compatibility. Prefer /ai/openai/chat/completions for new code.

Choosing a model

OpenAI (most integrations).

• gpt-5.4-nano — classification, extraction, short replies, high QPS.
• gpt-5.4-mini — default for chat, tools, and agents; best everyday choice.
• gpt-5.4 — multi-step reasoning, difficult coding, or when mini quality is not enough.

Other providers.

• DeepSeek — cost-effective general chat (deepseek-chat) and reasoning (deepseek-r1*).
• Claude — long instructions and careful prose; Sonnet for balance, Haiku for speed.
• Llama (Together) — open-weight models without a direct OpenAI account.
• Mistral — European-hosted alternative with OpenAI-like chat API.

Model pricing and context windows are stored in our api_models catalog and applied when calculating balance deductions.

Cost tracking

Every completed request is logged with provider, model, token counts, duration, and USD cost. Charges are deducted from the balance on your API user account (api_users.usd_available).

• Failed requests are logged with status=error and typically incur no token charge.
• Request/response payloads are stored for audit (api_request_data, transaction tables).
• For balance and access questions, contact studio@koveh.com.

Related services