Obrolan kompatibel OpenAI

Gunakan POST /v1/chat/completions dan GET /v1/models dengan OpenAI Python atau JavaScript SDK dengan mengubah URL dasar dan kunci API. Ini adalah kompatibilitas Penyelesaian Obrolan teks, bukan dukungan untuk setiap titik akhir atau kemampuan OpenAI.

Otentikasi dan model

Gunakan kunci API konsol yang sama: Authorization: Bearer sk-your-key. Daftar model berisi model teks yang tersedia saat ini dan ID publiknya. Gunakan id yang dikembalikan; jangan gunakan nama tampilan. Harga dan ID suara tetap tersedia di /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"}]}

Permintaan dan riwayat percakapan

Setiap permintaan menyediakan susunan messages lengkap secara berurutan. Peran yang didukung: system, developer, user, assistant, tool. Konten dapat berupa string atau array yang terdiri dari bagian { "type": "text", "text": "..." }. Tidak ada riwayat server atau persona default yang ditambahkan. Setiap giliran harus menyertakan instruksi sistem yang diperlukan dan riwayat yang relevan.

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

Parameter yang didukung

model dan array messages yang tidak kosong diperlukan. Opsional: stream (default false), temperature (0–2), top_p (0–1), max_tokens atau max_completion_tokens (bilangan bulat 1–8192, saling eksklusif), stop (satu string atau 1–4 string), presence_penalty dan frequency_penalty (−2–2), seed (bilangan bulat aman), n (hanya 1). Pengaturan pembuatan yang dihilangkan menggunakan default layanan; efek parameter pengambilan sampel bergantung pada model yang dipilih. stream_options: {"include_usage": true} hanya valid dengan stream: true. Nilai null opsional menggunakan default. Batas isi HTTP JSON adalah 15 MiB; batas konteks token bergantung pada model.

Streaming dan penggunaan

Streaming menggunakan SSE khusus data, tanpa event: delta atau event: completed khusus. Baca choices[0].delta.content, lalu finish_reason terakhir (stop, length atau content_filter, tool_calls) dan data: [DONE]. Dengan include_usage: true, potongan tambahan dengan choices: [] dan usage terakhir mendahului [DONE]; potongan lainnya memiliki usage: null. Tanpanya, potongan streaming menghilangkan penggunaan. Semua potongan berbagi ID penyelesaian lokal, waktu pembuatan, dan ID model publik.

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

Kesalahan dan cakupan yang didukung

Kesalahan menggunakan { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } }. HTTP 400 berarti masukan tidak valid atau tidak didukung; 401 kunci tidak valid, 402 kredit tidak mencukupi, 429 pembatasan tarif, 503 kegagalan layanan sementara, dan 504 batas waktu habis. Kesalahan dibersihkan. Sebelum streaming dimulai, kegagalan menggunakan kesalahan HTTP JSON; setelah dimulai, bingkai data: {"error": ...} mengakhiri streaming tanpa penanda keberhasilan. Jangan anggap tanggapan parsial sudah selesai. Batas waktu teks pertama: 90 detik; batas waktu menganggur: 60 detik, disetel ulang setiap delta teks. Waktu tunggu permintaan non-streaming habis setelah 60 detik.

Tidak didukung: input gambar/audio, pencarian dan eksekusi kode terkelola, functions / function_call lama, jenis alat kustom, logprobs, beberapa kandidat, store, Responses API, serta parameter yang tidak tercantum. Permintaan ditolak, bukan diabaikan. Gunakan /v1/chat/speech untuk suara.

Contoh Penagihan dan SDK

Saldo yang sama, harga model publik dan penagihan token input/output berlaku. Kredit dicadangkan sebelum pembuatan dan diselesaikan menggunakan penggunaan yang dilaporkan; reservasi yang tidak digunakan dilepaskan. Kegagalan pembangkitan, penggunaan yang tidak valid, atau pemutusan hubungan sebelum penyelesaian melepaskan reservasi. Pembatalan setelah penyelesaian berhasil tidak membatalkan tagihan. Panggilan muncul di Riwayat penggunaan dan dasbor admin; respons JSON standar berisi usage, bukan bidang billing khusus. Mengulangi permintaan mungkin dikenakan biaya lain; tidak ada idempotensi yang disediakan.

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

Alat agen dan keluaran terstruktur

Periksa models[].capabilities di /v1/chat/catalog: tool_calling, parallel_tool_calls, json_mode, structured_outputs. Dukungan bergantung pada model; kemampuan yang tidak didukung mengembalikan HTTP 400 sebelum generasi. Alat dijalankan oleh aplikasi Anda. API tidak menjalankan fungsi atau menyimpan memori agen.

Gunakan tools (maksimal 128 fungsi), tool_choice (auto, none, required, atau fungsi tertentu), dan parallel_tool_calls (boolean, memerlukan tools). Fungsi menerima name, description, parameters JSON Schema, serta strict opsional. Baca message.tool_calls; content boleh null. Tambahkan pesan assistant tanpa perubahan, lalu satu pesan role: "tool" untuk setiap panggilan dengan tool_call_id yang sesuai. Kirim semua hasil, termasuk kegagalan, sebelum panggilan model berikutnya. Pertahankan ID unik dan urutan pesan.

Saat streaming, kelompokkan choices[0].delta.tool_calls berdasarkan index, gabungkan fragmen function.arguments, dan simpan id, type, function.name. Jalankan hanya setelah finish_reason: "tool_calls" dan stream selesai dengan sukses; jangan jalankan keluaran length atau galat. Delta alat juga mengatur ulang batas idle 60 detik; batas keluaran pertama adalah 90 detik. Validasi nama, argumen, izin, dan batasi jumlah putaran.

response_format mendukung text, json_object, atau json_schema dengan json_schema: {name, schema, strict, description?}. Dalam mode JSON, minta JSON secara eksplisit dalam prompt. Schema ketat memerlukan semua properti dalam required serta additionalProperties: false; null dapat mewakili nilai opsional. Jangan gabungkan JSON Schema dengan parallel_tool_calls: true. Periksa refusal, length, dan galat sebelum parsing. Schema tidak menjamin kebenaran fakta. Definisi alat, argumen, dan hasil dihitung sebagai token; setiap putaran model ditagih terpisah.

Siklus alat lengkap

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

Contoh keluaran terstruktur

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)