Чат, совместимый с OpenAI

Используйте POST /v1/chat/completions и GET /v1/models с OpenAI Python или JavaScript SDK, изменив базовый URL-адрес и ключ API. Это совместимость с завершением текстового чата, а не поддержка каждой конечной точки или возможности OpenAI.

Аутентификация и модели

Используйте тот же ключ API консоли: Authorization: Bearer sk-your-key. Список моделей содержит доступные на данный момент текстовые модели и их общедоступные идентификаторы. Используйте возвращенный id; не используйте отображаемое имя. Цены и голосовые идентификаторы остаются доступными в /v1/chat/catalog.

curl https://api.coldstart.win/v1/models -H "Authorization: Bearer sk-your-key"

{"object":"list","data":[{"id":"chat-standard","object":"model","created":0,"owned_by":"girllab"}]}

Запросы и история разговоров

Каждый запрос приводит в порядок весь массив messages. Поддерживаемые роли: system, developer, user, assistant, tool. Содержимое может быть строкой или массивом частей { "type": "text", "text": "..." }. Никакая история сервера или персонаж по умолчанию не добавляются. Каждый ход должен включать необходимые системные инструкции и соответствующую историю.

curl https://api.coldstart.win/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"chat-standard","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}],"max_tokens":256}'

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1792540800,
  "model": "chat-standard",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!", "refusal": null}, "logprobs": null, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 3, "total_tokens": 15}
}

Поддерживаемые параметры

Требуется model и непустой массив messages. Необязательно: stream (по умолчанию false), temperature (0–2), top_p (0–1), max_tokens или max_completion_tokens (целое число от 1 до 8192, взаимоисключающее), stop (одна строка или 1–4 строки), presence_penalty и frequency_penalty (−2–2), seed (безопасное целое число), n (только 1). Пропущенные настройки генерации используют настройки службы по умолчанию; Эффекты параметров выборки зависят от выбранной модели. stream_options: {"include_usage": true} действителен только с stream: true. Необязательные нулевые значения используют значения по умолчанию. Предел тела HTTP JSON составляет 15 МБ; Ограничения контекста токена зависят от модели.

Потоковая передача и использование

Потоковая передача использует SSE только для данных, без специального event: delta или event: completed. Прочтите choices[0].delta.content, затем последний finish_reason (stop, length или content_filter, tool_calls) и data: [DONE]. В случае include_usage: true дополнительный фрагмент с choices: [] и конечный usage предшествуют [DONE]; другие чанки имеют usage: null. Без него потоковые фрагменты не используются. Все чанки имеют общий идентификатор локального завершения, время создания и идентификатор общедоступной модели.

{"model":"chat-standard","messages":[{"role":"user","content":"Hello!"}],"stream":true,"stream_options":{"include_usage":true}}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[{"index":0,"delta":{"content":"Hello!"},"logprobs":null,"finish_reason":null}],"usage":null}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null}

data: {"id":"chatcmpl_example","object":"chat.completion.chunk","created":1792540800,"model":"chat-standard","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}

data: [DONE]

Ошибки и поддерживаемая область действия

При ошибках используйте { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } }. HTTP 400 означает неверный или неподдерживаемый ввод; 401 неверный ключ, 402 недостаточно кредитов, 429 ограничение скорости, 503 временный сбой службы и 504 тайм-аут. Ошибки исправляются. Перед началом потоковой передачи при сбоях используется ошибка HTTP JSON; после его начала кадр data: {"error": ...} завершает поток без маркера успеха. Не считайте частичный ответ завершенным. Тайм-аут первого текста: 90 секунды; тайм-аут простоя: 60 секунд, сбрасывается каждой текстовой дельтой. Тайм-аут непотоковых запросов истекает через 60 секунд.

Не поддерживаются: изображения/аудио на входе, встроенный поиск и выполнение кода, устаревшие functions / function_call, пользовательские типы инструментов, logprobs, несколько кандидатов, store, Responses API и неуказанные параметры. Такие запросы отклоняются. Для речи используйте /v1/chat/speech.

Примеры биллинга и SDK

Применяются тот же баланс, цены общедоступной модели и выставление счетов за токены ввода/вывода. Кредиты резервируются перед генерацией и рассчитываются на основе отчетов об использовании; неиспользованные резервирования освобождаются. Сбой генерации, недопустимое использование или отключение до того, как расчет приведет к отмене резервирования. Отмена после успешного урегулирования не отменяет платеж. Звонки отображаются в истории использования и на панели администратора; стандартный ответ JSON содержит usage, а не пользовательское поле billing. Повторный запрос может повлечь за собой дополнительную плату; идемпотентность не обеспечивается.

pip install openai
npm install openai

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["KARMAN_API_KEY"], base_url="https://api.coldstart.win/v1", max_retries=0)
print([model.id for model in client.models.list().data])
model = os.environ["KARMAN_MODEL"]
messages = [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}]
reply = client.chat.completions.create(model=model, messages=messages, max_tokens=256)
print(reply.choices[0].message.content)

stream = client.chat.completions.create(model=model, messages=messages, max_tokens=256,
    stream=True, stream_options={"include_usage": True})
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.KARMAN_API_KEY, baseURL: "https://api.coldstart.win/v1", maxRetries: 0 });
const models = await client.models.list();
console.log(models.data.map(model => model.id));
const stream = await client.chat.completions.create({
  model: process.env.KARMAN_MODEL,
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true }
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
  if (chunk.usage) console.log("\n", chunk.usage);
}

Инструменты агента и структурированный вывод

Проверьте models[].capabilities в /v1/chat/catalog: tool_calling, parallel_tool_calls, json_mode, structured_outputs. Возможности зависят от модели; неподдерживаемые функции возвращают HTTP 400 до генерации. Инструменты выполняет ваше приложение. API не выполняет функции и не хранит память агента.

Поддерживаются tools (до 128 функций), tool_choice (auto, none, required или конкретная функция) и parallel_tool_calls (boolean, нужны tools). Функция содержит name, description, parameters в JSON Schema и необязательный strict. Читайте message.tool_calls; content может быть null. Добавьте сообщение assistant без изменений, затем по одному сообщению role: "tool" с соответствующим tool_call_id на каждый вызов. Перед следующим обращением к модели верните все результаты, включая ошибки. Сохраняйте уникальность ID и порядок сообщений.

При стриминге группируйте choices[0].delta.tool_calls по index, соединяйте фрагменты function.arguments и сохраняйте id, type, function.name. Выполняйте вызовы только после finish_reason: "tool_calls" и успешного завершения потока; при length или ошибке не выполняйте их. Дельты инструментов также сбрасывают тайм-аут простоя 60 секунд; ожидание первого вывода ограничено 90 секундами. Проверяйте имена, аргументы и права, ограничивайте число циклов.

response_format поддерживает text, json_object и json_schema с json_schema: {name, schema, strict, description?}. В режиме JSON явно запросите JSON в инструкции. Строгая схема требует все свойства в required и additionalProperties: false; необязательные значения можно представить через null. Не сочетайте JSON Schema с parallel_tool_calls: true. Перед разбором проверьте refusal, length и ошибки. Схема не гарантирует достоверность фактов. Определения инструментов, аргументы и результаты учитываются в токенах; каждый вызов модели оплачивается отдельно.

Полный цикл инструментов

import os, json
from openai import OpenAI

client = OpenAI(api_key=os.environ["KARMAN_API_KEY"],
                base_url="https://api.coldstart.win/v1", max_retries=0)
model = os.environ["KARMAN_MODEL"]
tools = [{"type": "function", "function": {
    "name": "lookup_memory", "description": "Read a saved preference.",
    "parameters": {"type": "object", "properties": {"topic": {"type": "string"}},
                   "required": ["topic"], "additionalProperties": False},
    "strict": True
}}]
messages = [{"role": "user", "content": "What food do I like? Use my saved memory."}]

for _ in range(4):
    reply = client.chat.completions.create(
        model=model, messages=messages, tools=tools,
        tool_choice="auto", parallel_tool_calls=False, max_tokens=512)
    choice = reply.choices[0]
    message = choice.message
    if message.refusal or choice.finish_reason not in ("stop", "tool_calls"):
        raise RuntimeError("Incomplete or refused response")
    messages.append(message.model_dump(exclude_none=True))
    if not message.tool_calls:
        print(message.content)
        break
    for call in message.tool_calls:
        try:
            if call.function.name != "lookup_memory":
                raise ValueError("Unknown function")
            args = json.loads(call.function.arguments)
            if not isinstance(args, dict) or set(args) != {"topic"} or not isinstance(args["topic"], str):
                raise ValueError("Invalid arguments")
            result = {"topic": args["topic"], "preference": "apples"}
        except (ValueError, TypeError):
            result = {"error": "Invalid tool request"}
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
else:
    raise RuntimeError("Agent round limit reached")

Пример структурированного вывода

reply = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "I like apples. Extract this preference as JSON."}],
    response_format={"type": "json_schema", "json_schema": {
        "name": "memory", "strict": True,
        "schema": {"type": "object", "properties": {"preference": {"type": "string"}},
                   "required": ["preference"], "additionalProperties": False}
    }}, max_tokens=256)
choice = reply.choices[0]
if choice.finish_reason != "stop" or choice.message.refusal:
    raise RuntimeError("Incomplete or refused response")
memory = json.loads(choice.message.content)
print(memory)