OpenAI uyumlu sohbet

Temel URL'yi ve API anahtarını değiştirerek POST /v1/chat/completions ve GET /v1/models'i OpenAI Python veya JavaScript SDK ile kullanın. Bu, metin Sohbet Tamamlamaları uyumluluğudur; her OpenAI uç noktası veya özelliği için destek değildir.

Kimlik doğrulama ve modeller

Aynı konsol API anahtarını kullanın: Authorization: Bearer sk-your-key. Model listesi şu anda mevcut olan metin modellerini ve bunların genel kimliklerini içerir. Döndürülen id'i kullanın; görünen ad kullanmayın. Fiyatlar ve ses kimlikleri /v1/chat/catalog'te mevcuttur.

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

İstekler ve konuşma geçmişi

Her istek, messages dizisinin tamamını sırayla sağlar. Desteklenen roller: system, developer, user, assistant, tool. İçerik bir dizi veya { "type": "text", "text": "..." } parçalarından oluşan bir dizi olabilir. Hiçbir sunucu geçmişi veya varsayılan kişi eklenmez. Her tur gerekli sistem talimatlarını ve ilgili geçmişi içermelidir.

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

Desteklenen parametreler

model ve boş olmayan bir messages dizisi gereklidir. İsteğe bağlı: stream (varsayılan false), temperature (0–2), top_p (0–1), max_tokens veya max_completion_tokens (tamsayı) 1–8192, birbirini dışlayan), stop (bir dize veya 1–4 dizeleri), presence_penalty ve frequency_penalty (−2–2), seed (güvenli) tamsayı), n (yalnızca 1). Atlanan oluşturma ayarları hizmet varsayılanlarını kullanır; örnekleme parametrelerinin etkileri seçilen modele bağlıdır. stream_options: {"include_usage": true} yalnızca stream: true ile geçerlidir. İsteğe bağlı boş değerler varsayılanları kullanır. HTTP JSON gövde sınırı 15 MiB'dir; belirteç bağlam sınırları modele bağlıdır.

Akış ve kullanım

Akış, özel event: delta veya event: completed olmadan yalnızca veri içeren SSE'i kullanır. choices[0].delta.content'i, ardından son finish_reason'i (stop, length veya content_filter, tool_calls) ve data: [DONE]'i okuyun. include_usage: true ile, choices: [] ve son usage ile ekstra bir parça [DONE]'ten önce gelir; diğer parçalarda usage: null bulunur. Bu olmadan, akış parçaları kullanımı atlar. Tüm parçalar yerel bir tamamlama kimliğini, oluşturma zamanını ve genel model kimliğini paylaşır.

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

Hatalar ve desteklenen kapsam

Hatalarda { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } kullanılır. HTTP 400, geçersiz veya desteklenmeyen giriş anlamına gelir; 401 geçersiz anahtar, 402 yetersiz kredi, 429 oran sınırlaması, 503 geçici hizmet hatası ve 504 zaman aşımı. Hatalar arındırılır. Akış başlamadan önce hatalar bir HTTP JSON hatası kullanır; başladıktan sonra, bir data: {"error": ...} çerçevesi, akışı bir başarı işareti olmadan sonlandırır. Kısmi bir yanıtı tamamlanmış olarak değerlendirmeyin. İlk metin zaman aşımı: 90 saniye; boşta kalma zaman aşımı: 60 saniye, her metin deltası ile sıfırlanır. Akış dışı istekler 60 saniye sonra zaman aşımına uğrar.

Desteklenmeyenler: görüntü/ses girdileri, barındırılan arama ve kod yürütme, eski functions / function_call, özel araç türleri, logprobs, birden çok aday, store, Responses API ve listelenmeyen parametreler. Bunlar açıkça reddedilir. Ses için /v1/chat/speech kullanın.

Faturalandırma ve SDK örnekleri

Aynı denge, genel model fiyatları ve girdi/çıktı jetonu faturalandırması geçerlidir. Krediler oluşturulmadan önce rezerve edilir ve bildirilen kullanım kullanılarak kapatılır; Kullanılmayan rezervasyonlar iptal edilir. Üretim hatası, geçersiz kullanım veya ödeme yapılmadan önce bağlantının kesilmesi, rezervasyon iptal edilir. Başarılı bir anlaşmanın ardından yapılan iptal, ücreti geri almaz. Aramalar Kullanım geçmişinde ve yönetici kontrol panelinde görünür; standart JSON yanıtı, özel bir billing alanı değil, usage içerir. Bir talebin tekrarlanması başka bir ücrete tabi olabilir; hiçbir idempotency sağlanmaz.

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);
}

Ajan araçları ve yapılandırılmış çıktı

/v1/chat/catalog içindeki models[].capabilities alanını kontrol edin: tool_calling, parallel_tool_calls, json_mode, structured_outputs. Destek modele bağlıdır; desteklenmeyen yetenekler üretimden önce HTTP 400 döndürür. Araçlar uygulamanızda çalıştırılır. API işlev yürütmez veya ajan belleği saklamaz.

tools (en fazla 128 işlev), tool_choice (auto, none, required veya belirli bir işlev) ve parallel_tool_calls (boolean, tools gerektirir) desteklenir. İşlevler name, description, JSON Schema parameters ve isteğe bağlı strict içerir. message.tool_calls alanını okuyun; content null olabilir. Assistant mesajını aynen geçmişe ekleyin ve her çağrı için eşleşen tool_call_id ile bir role: "tool" mesajı gönderin. Başarısızlıklar dahil tüm sonuçları sonraki model çağrısından önce döndürün; benzersiz kimlikleri ve sırayı koruyun.

Akışta choices[0].delta.tool_calls verilerini index ile gruplayın, function.arguments parçalarını birleştirin ve id, type, function.name alanlarını saklayın. Yalnızca finish_reason: "tool_calls" ve başarılı akış bitişinden sonra çalıştırın; length veya hatalı çıktıyı çalıştırmayın. Araç deltaları da 60 saniyelik boşta kalma süresini sıfırlar; ilk çıktı sınırı 90 saniyedir. Adları, argümanları ve izinleri doğrulayın, tur sayısını sınırlayın.

response_format, text, json_object veya json_schema: {name, schema, strict, description?} içeren json_schema kabul eder. JSON modunda istemde açıkça JSON isteyin. Katı şemalarda tüm özellikler required olmalı ve additionalProperties: false ayarlanmalıdır; isteğe bağlı değerler null olabilir. JSON Schema ile parallel_tool_calls: true birlikte kullanılamaz. Ayrıştırmadan önce refusal, length ve hataları kontrol edin. Şema olgusal doğruluğu garanti etmez. Araç tanımları, argümanlar ve sonuçlar token hesabına dahildir; her model turu ayrı ücretlendirilir.

Tam araç döngüsü

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

Yapılandırılmış çıktı örneği

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)