Penyiapan API Windsurf yang kompatibel dengan OpenAI: Arahkan traffic coding agent melalui satu kunci

Jika Anda mencari penyiapan Windsurf OpenAI compatible API, kemungkinan besar yang Anda maksud adalah salah satu dari dua hal yang berbeda:

• Anda ingin mengubah model yang digunakan Windsurf atau Devin Desktop di dalam Cascade.
• Anda ingin kode, skrip, alat, atau aplikasi lokal yang dibantu Windsurf Anda buat mengirim traffic API yang kompatibel dengan OpenAI melalui satu kunci gateway bersama.

Kedua hal itu bukan penyiapan yang sama. Dokumentasi publik Windsurf dan Devin Desktop yang diperiksa pada 2026-07-08 mendokumentasikan pemilihan model Cascade, Devin Local, pencatatan penggunaan/kredit, dan server MCP untuk alat. Dokumentasi tersebut tidak menjelaskan layar native "custom OpenAI-compatible provider" tempat Anda menempelkan base URL LLM pihak ketiga untuk Cascade itu sendiri.

Hal ini penting karena pola Flatkey yang aman bukan berpura-pura bahwa Windsurf memiliki field provider native yang tidak ditampilkan di dokumen. Gunakan Flatkey untuk SDK dan traffic aplikasi yang kompatibel dengan OpenAI di sekitar proyek yang digerakkan Windsurf: skrip pengujian, alat agent, layanan backend, workflow CLI, dan kode aplikasi yang sudah memanggil endpoint bergaya Chat Completions.

Flatkey memberi traffic itu satu kunci, base URL yang kompatibel dengan OpenAI, routing model, visibilitas penggunaan, dan peninjauan penagihan. Windsurf tetap menjadi lingkungan coding; Flatkey menjadi rute API yang digunakan kode proyek Anda.

Jawaban cepat untuk penyiapan Windsurf OpenAI compatible API

Gunakan tabel keputusan ini sebelum mengubah konfigurasi.

Jalur praktis Windsurf OpenAI compatible API adalah: biarkan Windsurf membantu mengedit kode, tetapi arahkan panggilan model kode melalui Flatkey. Itu membuat penyiapan Windsurf OpenAI compatible API tetap dapat diaudit karena lingkungan coding, kunci API, dan rute produksi masing-masing memiliki pemilik yang jelas.

Apa yang sebenarnya didukung oleh dokumentasi resmi Windsurf dan Devin

Dokumentasi publik saat ini mendukung tiga fakta yang membentuk panduan ini.

Jadi artikel Windsurf OpenAI compatible API sebaiknya tidak mengatakan, "Buka pengaturan Windsurf dan tambahkan Flatkey sebagai penyedia OpenAI kustom," kecuali dokumentasi langsung atau UI produk yang Anda gunakan memang jelas menampilkan kemampuan itu. Panduan produksi yang lebih aman adalah mengonfigurasi kode dan alat yang dihasilkan Windsurf.

Langkah 1: Buat kunci Flatkey dan pilih rutenya

Di Flatkey, buat kunci untuk beban kerja ini dan pilih alias model yang cocok dengan keluarga endpoint yang akan Anda panggil. Untuk rute bergaya Chat Completions, pisahkan root API dan endpoint:

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

Untuk panggilan curl langsung, tambahkan path endpoint:

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

Jangan berikan SDK baik https://router.flatkey.ai/v1 maupun /chat/completions sebagai base URL. Base URL SDK biasanya harus berhenti di /v1; request curl langsung memakai endpoint lengkap.

Langkah 2: Tempatkan rute di factory klien SDK

Penyiapan Windsurf OpenAI compatible API yang paling berguna adalah boundary klien kecil yang dapat diedit Windsurf dengan aman. Simpan secret di variabel environment dan buat alias model dapat dikonfigurasi.

Template Python:

import os
from openai import OpenAI


def make_llm_client() -> OpenAI:
    return OpenAI(
        api_key=os.environ["FLATKEY_API_KEY"],
        base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
    )


client = make_llm_client()

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[
        {"role": "user", "content": "Reply with exactly: sdk route ok"}
    ],
)

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

Template Node:

import OpenAI from "openai";

export function makeLlmClient() {
  return new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
  });
}

const client = makeLlmClient();

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [
    { role: "user", content: "Balas dengan tepat: sdk route ok" },
  ],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

Anggap potongan kode ini sebagai template sampai Anda mengujinya terhadap versi SDK yang terpasang, kunci Flatkey saat ini, alias model saat ini, dan keluarga endpoint yang digunakan. Jika aplikasi Anda sudah memiliki pembungkus base-URL, perbarui pembungkus itu alih-alih menyebarkan variabel Flatkey ke seluruh controller dan skrip.

Untuk detail migrasi spesifik SDK, pasangkan panduan ini dengan panduan Flatkey untuk penyiapan API Cursor yang kompatibel dengan OpenAI dan penyiapan router API Claude Code.

Step 3: Minta Windsurf melakukan perubahan kode, bukan menyimpan secret

Windsurf berguna untuk menerapkan migrasi di seluruh repo, tetapi prompt harus membatasi pekerjaannya.

Perbarui setup client LLM agar semua request chat yang kompatibel dengan OpenAI menggunakan:
- FLATKEY_API_KEY untuk bearer token
- FLATKEY_BASE_URL sebagai root API
- FLATKEY_MODEL sebagai alias model

Jangan hardcode secret.
Jangan ubah prompt, logika bisnis, atau kebijakan retry.
Perbarui hanya factory client dan test terkecil yang diperlukan untuk memverifikasi route.

Itu membuat pekerjaan Windsurf OpenAI compatible API tetap terfokus pada konfigurasi, bukan refactor besar.

Step 4: Pisahkan konfigurasi MCP

Ini adalah kesalahan setup yang paling umum. Konfigurasi MCP Windsurf menghubungkan Cascade ke tools. Entri MCP remote bisa terlihat seperti ini:

{
  "mcpServers": {
    "internal-docs": {
      "serverUrl": "https://tools.example.com/mcp"
    }
  }
}

serverUrl itu bukan tempat Anda menaruh https://router.flatkey.ai/v1. Server MCP dapat mengekspos tools ke Cascade, dan tools tersebut mungkin memanggil Flatkey secara internal jika Anda membangunnya seperti itu. Namun, konfigurasi transport MCP dan routing model yang kompatibel dengan OpenAI adalah lapisan yang berbeda.

Gunakan pemisahan ini:

Jika server MCP Anda memanggil sebuah model, letakkan kunci Flatkey di sisi server MCP, bukan di konfigurasi client Windsurf, kecuali model keamanan Anda secara eksplisit mengizinkan kredensial developer lokal.

Step 5: Simpan paket verifikasi

Migrasi Windsurf OpenAI compatible API siap hanya ketika Anda dapat membuktikan rutenya berfungsi dan dapat di-rollback. Tujuan dari paket verifikasi Windsurf OpenAI compatible API adalah membuat perubahan rute pertama cukup kecil untuk diperiksa bersama oleh engineering, finance, dan operations.

Untuk field usage yang lebih mendalam, gunakan panduan dashboard token usage setelah smoke test pertama berhasil.

Step 6: Uji streaming dan tools setelah chat biasa

Jangan mulai dari route yang paling sulit. Buktikan dulu request chat non-streaming. Lalu uji streaming dan panggilan tool sebagai kontrak terpisah.

Bukti streaming:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Hitung dari satu sampai lima." }
    ]
  }'

Bukti tool-call sebaiknya menggunakan satu skema fungsi kecil sebelum Anda mencoba toolset produksi:

{
  "type": "function",
  "function": {
    "name": "lookup_ticket",
    "description": "Return a test ticket status.",
    "parameters": {
      "type": "object",
      "properties": {
        "ticket_id": { "type": "string" }
      },
      "required": ["ticket_id"]
    }
  }
}

Jika chat biasa berhasil tetapi streaming atau tools gagal, Anda tidak lagi sedang men-debug base URL. Anda sedang memeriksa kemampuan route, dukungan model, parsing SDK, atau perilaku gateway untuk fitur tersebut.

Tabel pemecahan masalah

Daftar periksa akhir

Sebelum meningkatkan traffic, konfirmasi:

1. Tujuannya adalah traffic aplikasi, skrip, atau tool di sekitar Windsurf, bukan pengaturan penyedia native Cascade yang tidak terdokumentasi.
2. FLATKEY_API_KEY, FLATKEY_BASE_URL, dan FLATKEY_MODEL dikonfigurasi di luar source control.
3. Curl langsung berhasil terhadap $FLATKEY_BASE_URL/chat/completions.
4. Factory SDK aplikasi menggunakan kunci, base URL, dan alias model yang sama.
5. Streaming dan tools diuji terpisah dari chat biasa.
6. Penggunaan Flatkey atau log request menampilkan request uji.
7. Nilai rollback dicatat sebelum traffic produksi dipindahkan.

Setup Windsurf OpenAI compatible API berguna ketika jujur tentang batasnya: Windsurf membantu Anda membangun dan memodifikasi kode, sementara Flatkey merutekan panggilan yang kompatibel dengan OpenAI yang dibuat kode tersebut. Saat Anda siap merutekan panggilan itu melalui satu kunci, dapatkan kunci Flatkey dan mulai dengan satu smoke test berisiko rendah.