Panduan Integrasi API DeepSeek: Permintaan Kompatibel dengan OpenAI melalui ECAIX

Dokumen ini menjelaskan bagaimana menguji model ID DeepSeek melalui ECAIX menggunakan endpoint API yang kompatibel dengan OpenAI. Topik yang dibahas meliputi permintaan minimal yang berfungsi, contoh Python dan curl, verifikasi model ID, streaming, keluaran struktur, tools, dan jalur diagnostik untuk kesalahan umum.

Dokumen ini menjelaskan akses gateway ECAIX ke model ID yang tersedia dalam katalog saat ini ECAIX. Tidak ada jaminan bahwa ECAIX adalah endpoint resmi API DeepSeek atau bahwa semua fitur DeepSeek dapat diakses melalui setiap jalur gateway. Periksa halaman model live dan dokumentasi penyedia sebelum memindahkan beban kerja ke produksi.

Mulai cepat

Gunakan urutan ini jika Anda sudah memiliki aplikasi dengan SDK OpenAI:

1. Buka halaman DeepSeek v4.1 Flash model dan konfirmasi bahwa ID tersedia.
2. Buat ECAIX API key.
3. Setel URL basis kompatibel dengan OpenAI ke https://ecaix.com/api/ai/v1.
4. Jaga SDK dan kode aplikasi tetap tidak berubah di mana mungkin.
5. Jalankan permintaan minimal di bawah ini.
6. Tambahkan streaming, keluaran JSON, atau tools hanya setelah permintaan dasar berfungsi.

Endpoint dan model ID

Untuk klient kompatibel dengan OpenAI, gunakan:

Base URL: https://ecaix.com/api/ai/v1
Model:    deepseek-v4.1-flash

ID model tidak merupakan jaminan permanen dalam artikel blog. Konfirmasinya di direktorat model live sebelum setiap integrasi atau deploy baru. Jika Anda membutuhkan anggota keluarga DeepSeek yang berbeda, salin ID yang tepat dari halaman detail model, bukan dengan menebak sufix.

Format endpoint juga penting. SDK harus menerima path basis yang berakhir di /v1; klient menambahkan /chat/completions atau jalur operasi lainnya. Jangan tambahkan /chat/completions ke base_url jika SDK sudah menambahkan itu sendiri.

Python dengan SDK OpenAI

Pasang atau upgrade SDK Python OpenAI di lingkungan virtual Anda:

python -m pip install --upgrade openai

Lalu gunakan URL basis ECAIX dan kunci API:

const client = new OpenAI({
  apiKey: process.env.ECAIX_API_KEY,
  baseURL: "https://ecaix.com/api/ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [
    { role: "user", content: "Return one short sentence about API testing." },
  ],
  max_tokens: 128,
});

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

Gunakan kode server-side untuk permintaan API. Aplikasi browser harus memanggil backend Anda sendiri daripada mengungkapkan kunci ECAIX di dalam skrip JavaScript client-side.

Permintaan Diagnostik dengan Curl

Jika SDK gagal, hapus SDK dari perspektif dan uji endpoint langsung. Simpan header dan body terpisah agar Anda dapat membedakan masalah HTTP dengan masalah format respons.

curl -sS -D /tmp/ecaix-deepseek-headers.txt \
  -o /tmp/ecaix-deepseek-response.json \
  -w '\nHTTP %{http_code}\n' \
  "https://ecaix.com/api/ai/v1/chat/completions" \
  -H "Authorization: Bearer ${ECAIX_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ],
    "max_tokens": 128
  }'

Jangan pastekan header atau respons yang disimpan ke dalam ticket publik tanpa menghapus kunci API, ID permintaan, prompt, path repository, dan data pelanggan.

Bagaimana untuk mendiagnosa respons

Ikuti urutan berikut:

1. Kode status HTTP: pastikan permintaan mencapai endpoint yang valid.
2. Bodys respons: baca kode kesalahan dari provider atau gateway.
3. ID model: salin ID model yang tepat dari direktori model saat ini.
4. Authentikasi: cek header kunci, akun, dan izin.
5. Form permintaan: reduksi isi menjadi model, messages, dan batas output kecil.
6. Layar fitur: tambahkan streaming, JSON, atau alat satu per satu.
7. Perilaku SDK: bandingkan permintaan SDK dengan permintaan curl langsung.

Hal ini mencegah masalah di dalam library klient disalahidentifikasi sebagai rute model atau izin akun.

Respon streaming

Jika aplikasi membutuhkan output berkelanjutan, tambahkan streaming hanya setelah permintaan normal berhasil:

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Summarize API retries in three points."}],
    stream=True,
    max_tokens=256,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Perilaku event yang tepat bergantung pada endpoint dan SDK. Verifikasi bagaimana kerangka kerja Anda menangani delta kosong, event penggunaan akhir, interupsi koneksi, dan penandaan seperti [DONE]. Jangan menganggap implementasi streaming sebagai siap produksi sampai Anda telah menguji interupsi dan retry.

Output berstruktur dan JSON

Jika Anda membutuhkan output yang dapat dibaca mesin, mulai dengan permintaan biasa kemudian tambahkan opsi output berstruktur terkecil yang didukung oleh endpoint dan model. Validasi isi respons dengan parser JSON yang benar. Prompt yang mengatakan “kembalikan JSON” tidak sama dengan respons yang dipaksa oleh schema.

import json

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with keys title and priority."
        }
    ],
    response_format={"type": "json_object"},
    max_tokens=128,
)

payload = json.loads(response.choices[0].message.content)
print(payload["title"])

Apakah response_format diterima dapat bergantung pada model dan rute. Jika endpoint mengembalikan kesalahan parameter tidak didukung, hapus field tersebut dan verifikasi dokumentasi rute sebelum mencoba format lain.

Panggilan fungsi dan alat

Panggilan alat membutuhkan tes terpisah dari generasi teks. Mulai dengan satu fungsi tidak berbahaya dan inspect nama dan argumen yang dikembalikan sebelum menjalankan sesuatu.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_demo_status",
            "description": "Return a fixed status for a local compatibility test.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    }
]

response = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Check the demo status."}],
    tools=tools,
    tool_choice="auto",
    max_tokens=128,
)

print(response.choices[0].message.tool_calls)

Model mungkin mengembalikan respons teks yang valid sementara panggilan alat gagal karena konversi schema, parameter tidak didukung, atau perilaku khusus klient. Jangan menjalankan argumen alat yang dikembalikan ke sistem produksi sebelum memvalidasi schema dan menambahkan pengecekan otorisasi.

Path kompatibel OpenAI dan Anthropic

ECAIX menawarkan permukaan kompatibilitas yang berbeda untuk berbagai klient:

Baca dokumentasi Chat Completions, dokumentasi Responses, dan dokumentasi Messages Anthropic sebelum memilih path. ID model yang sama mungkin tidak menampilkan field atau perilaku yang sama di setiap permukaan kompatibilitas.

Detail model saat ini

Gunakan halaman detail langsung untuk pemeriksaan kemampuan dan ketersediaan:

• DeepSeek v4.1 Flash
• DeepSeek v4 Pro 202606
• Qwen 3.8 Flash
• GLM 5.3

Kesalahan umum

Checklist keamanan dan produksi

Sebelum melangkah di luar proyek uji, pastikan:

• Kunci API disimpan di server dan dapat dirotasi.
• Prompt dan respons tidak mengandung rahasia atau data pelanggan yang tidak disetujui.
• Anda memahami apakah gateway mencatat log permintaan dan berapa lama log disimpan.
• Ketersediaan model dan harga diperiksa dari halaman hidup.
• Timeout, retry, idempotensi, dan batasan rate diatur oleh aplikasi Anda.
• Disconnect streaming tidak menciptakan pekerjaan duplikat.
• Panggilan alat memiliki allowlist, validasi, otoritas, dan log audit.
• Syarat provider dan gateway memungkinkan pekerjaan yang Anda rencanakan kirimkan.

Catat integrasi sebelum rilis

Catat tanggal, versi klient, ID model, endpoint, status HTTP, dan uji fitur yang Anda sebenarnya jalankan. Jika uji tidak dilakukan, tanda sebagai belum diverifikasi. Catatan ini memudahkan perbandingan dengan model atau gateway yang baru dan mencegah asumsi produksi dari contoh blog lama menjadi asumsi yang tidak dukungan.

Pertanyaan umum (FAQ)

Apakah ini endpoint resmi DeepSeek API?

Tidak. Artikel ini mendokumentasikan akses gateway ECAIX ke model ID yang terpublikasikan dalam katalog ECAIX. Gunakan dokumentasi resmi DeepSeek API untuk endpoint DeepSeek asli, aturan akun, dan kemampuan provider khusus.

Apakah saya bisa menggunakan SDK OpenAI tanpa merubah aplikasi saya?

Beberapa aplikasi SDK OpenAI dapat dimulai dengan mengubah URL dasar, kunci API, dan ID model. Anda masih perlu menguji dukungan field, streaming, panggilan alat, format respons, pengolahan kesalahan, dan fitur provider khusus yang digunakan oleh aplikasi Anda.

Model DeepSeek mana yang saya pilih?

Awali dengan direktori model dan pilih berdasarkan tugas: pemrograman, pemikiran, panjang konteks, input multimodal, atau persyaratan biaya. Jangan hanya memilih berdasarkan nama yang dikopi dari artikel lama. Verifikasi ID model saat ini dan uji dengan prompt Anda sendiri.

Apakah saya bisa menggunakan ini dengan Claude Code?

Jalur yang kompatibel dengan Anthropic dapat diuji sebagai workflow provider pihak ketiga, tetapi Anthropic tidak mendukung rute Claude Code ke model non-Claude melalui gateway. Jangan presentasikan ini sebagai dukungan resmi Anthropic atau sebagai jaminan kompatibilitas penuh dengan Claude Code.

Di mana saya bisa memeriksa harga dan batasan saat ini?

Gunakan halaman harga ECAIX, direktori model, dan kontrol akun Anda. Jangan hardcode harga dari artikel ini ke dalam aplikasi Anda.

Langkah selanjutnya

1. Pastikan ID model di halaman model DeepSeek saat ini.
2. Buat kunci API ECAIX.
3. Baca dokumentasi Chat Completions.
4. Jalankan uji coba curl langsung.
5. Pergi ke contoh SDK hanya setelah permintaan langsung berhasil.
6. Tambahkan streaming, JSON, atau alat satu fitur demi satu.

## Validasi Pra-Produksi dan Best Practices Penggunaan API DeepSeek

Sebelum mengintegrasikan API DeepSeek ke dalam produksi, penting untuk melakukan validasi pra-produksi yang cermat agar sistem dapat beroperasi dengan stabil dan sesuai dengan kebutuhan bisnis. Berikut adalah panduan untuk mengoptimalkan proses pengujian dan pengelolaan API, termasuk aspek keamanan, keandalan, dan performa.

### 1. Validasi Pra-Produksi
Pastikan semua endpoint API, model ID, dan parameter yang digunakan telah diuji secara menyeluruh dalam lingkungan staging. Uji coba harus mencakup:
- **Kesesuaian dengan spesifikasi API** (misalnya, struktur request/response, status code, dan format data).
- **Ketepatan model** (misalnya, model `text-generation-1.5` atau `multimodal-1.0`) dengan kebutuhan aplikasi Anda.
- **Performa dan responsivitas** dengan beban traffic yang realistis.

Uji coba juga harus melibatkan pengujian **idempotensi** (misalnya, memastikan bahwa permintaan yang sama tidak menghasilkan hasil yang berbeda jika dijalankan ulang). Pastikan juga bahwa sistem dapat menangani **streaming disconnect** (misalnya, saat koneksi internet terputus selama proses generasi teks) dengan cara yang tidak merusak data atau menghasilkan kesalahan yang tidak dapat diatasi.

---

### 2. Pengelolaan API Key dan Keamanan
API key DeepSeek harus diajukan dan dikelola dengan hati-hati. Berikut beberapa praktik terbaik:
- **Jangan menyimpan API key dalam file atau variabel yang dapat diakses oleh siapa saja** (misalnya, dalam repository Git yang publik atau file konfigurasi yang tidak terenkripsi).
- **Gunakan variabel lingkungan atau sistem manajemen konfigurasi** (misalnya, AWS Secrets Manager, HashiCorp Vault) untuk menyimpan API key.
- **Limit akses API key** dengan mengatur **rate limiting** atau **IP whitelisting** jika diperlukan.
- **Rotasi API key secara berkala** untuk mengurangi risiko kebocoran data.

---

### 3. Pemeriksaan Model ID dan Konsistensi
Pastikan model ID yang digunakan benar-benar sesuai dengan yang diharapkan. Beberapa hal yang perlu diperhatikan:
- **Model ID yang digunakan harus stabil** (misalnya, tidak mengalami perubahan versi secara tiba-tiba).
- **Uji kembali model ID** sebelum mengintegrasikan API ke produksi, terutama jika ada perubahan dalam dokumentasi atau spesifikasi.
- **Periksa dokumentasi terbaru** untuk memastikan bahwa model yang digunakan mendukung semua fitur yang Anda butuhkan (misalnya, ukuran token, batasan panjang teks, atau dukungan multimodal).

---

### 4. Logging Request dan Response Tanpa Data Rahasia
Untuk debugging dan analisis performa, implementasikan logging yang memungkinkan tanpa mengungkapkan data rahasia (misalnya, API key, token, atau informasi pribadi). Contoh yang baik meliputi:
- **Log request** (misalnya, endpoint yang dipanggil, parameter, dan status HTTP).
- **Log response** (misalnya, status code, durasi respon, dan format data yang dikembalikan).
- **Jangan log data input/output yang mengandung informasi sensitif** (misalnya, teks yang dihasilkan atau data pribadi pelanggan).

Untuk melindungi data rahasia, gunakan **masking** (misalnya, mengganti API key dengan karakter baca-balik atau menandai log dengan tag yang tidak mengandung informasi sensitif).

---

### 5. Retry dan Idempotensi
API DeepSeek harus dirancang untuk menangani kesalahan dengan cara yang dapat diulang (retry) dan idempotent (tidak menghasilkan efek samping yang tidak diinginkan). Berikut beberapa strategi:
- **Implementasi retry dengan batasan** (misalnya, maksimal 3 kali retry untuk kesalahan temporary seperti timeout atau rate limit).
- **Gunakan parameter idempotency-key** (jika tersedia) untuk memastikan bahwa permintaan yang sama tidak diulang secara otomatis.
- **Uji kembali sistem** setelah terjadi kesalahan untuk memastikan bahwa data tidak hilang atau terduplikasi secara tidak sengaja.

---

### 6. Streaming dan