Panduan Integrasi API Takdir

Cara akses, model yang tersedia, spesifikasi permintaan, aturan kredit, dan contoh pemanggilan untuk API takdir YlanAI

Mar 25, 2026

Halaman ini menjelaskan pola integrasi standar untuk API takdir YlanAI.

Antarmuka saat ini mengikuti protokol yang kompatibel dengan OpenAI dan ditujukan untuk klien yang mendukung chat/completions dan completions.

1. Informasi akses

Alamat, metode request, dan endpoint standar

Item	Deskripsi
Base URL yang direkomendasikan	`https://ylan.ai/api/openai`
Base URL kompatibilitas	`https://ylan.ai/api/openai/v1`
Metode default	`POST`
Daftar model	`GET /models`
Detail model	`GET /models/{id}`
Endpoint percakapan	`POST /chat/completions`
Endpoint legacy `completions`	`POST /completions`

Untuk klien pihak ketiga yang menambahkan /v1 secara otomatis, gunakan https://ylan.ai/api/openai sebagai base URL.

Autentikasi

Semua permintaan harus menyertakan header berikut:

Authorization: Bearer sk-...

API Key terikat ke akun pengguna saat ini, dan konsumsi akan dipotong dari saldo kredit berbayar akun tersebut.

Untuk klien yang tidak dapat mengatur Authorization, kompatibilitas juga tersedia melalui api-key: sk-... dan x-api-key: sk-....

Percakapan multi-turn

Percakapan multi-turn didukung. Pemanggil dapat menjaga konteks berkelanjutan dengan mengirim riwayat percakapan melalui array messages.

2. Cakupan layanan dan model

Cakupan layanan

Cakupan	Deskripsi
Kapabilitas terbuka	Saat ini hanya API analisis takdir yang dibuka
Chat umum	Tidak dibuka
Skenario yang didukung	Mendukung analisis satu subjek dan analisis pasangan
Standar keluaran	Selaras dengan pengalaman produk di situs

Model yang tersedia

Referensi resmi mengikuti hasil real-time dari GET /models. Daftar model dapat berubah sesuai perkembangan kemampuan platform.

Model	Deskripsi
`openai/gpt-5.4`	Cocok untuk analisis takdir dengan tuntutan kualitas tinggi
`openai/gpt-5.3-chat`	Cocok untuk interpretasi umum dan percakapan multi-turn
`deepseek/deepseek-v3.2`	Cocok untuk analisis beragam dan percakapan multi-turn

3. Spesifikasi permintaan

Format respons

Skenario	Format respons
`stream=true`	Mengembalikan aliran SSE kompatibel OpenAI dengan payload `chat.completion.chunk` dan penutup `data: [DONE]`
`stream=false`	Mengembalikan respons JSON standar `chat.completion`
`POST /completions`	Mengembalikan JSON `text_completion` kompatibel OpenAI atau aliran SSE
Header non-stream berhasil	Menyertakan `x-ylan-charged-credits` dan `x-ylan-remaining-paid-credits`

Parameter permintaan

Parameter	Tipe	Deskripsi
`model`	`string`	Nama model yang dikembalikan oleh `GET /models`
`messages`	`array`	Array pesan kompatibel OpenAI; harus berisi minimal satu pesan `user`
`prompt`	`string`	Input legacy untuk `completions`; dapat digunakan ketika `messages` tidak dikirim
`input`	`string`	Field input kompatibilitas untuk beberapa klien pihak ketiga ketika `messages` tidak dikirim
`stream`	`boolean`	Apakah menggunakan respons streaming. Nilai default `false`
`locale`	`string`	Bahasa keluaran, misalnya `id`, `zh`, `en`
`topic`	`string`	Topik takdir, misalnya `wealth_pattern` atau `marriage_status`
`subject_mode`	`string`	Mode analisis: `single` atau `pair`
`method`	`string`	Metode analisis yang ditafsirkan oleh rantai fortune saat ini
`birth_profile`	`object`	Input data kelahiran untuk analisis satu subjek
`chart_input`	`object`	Input bagan terstruktur untuk skenario dengan bagan yang sudah disiapkan
`pair_state`	`object`	Input untuk analisis pasangan
`metadata`	`object`	Metadata tambahan yang dapat melengkapi `topic`, `locale`, `birthProfile`, `pairState`, dan lainnya

Contoh streaming satu subjek

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-5.4",
    "stream": true,
    "locale": "id",
    "topic": "wealth_pattern",
    "subject_mode": "single",
    "birth_profile": {
      "calendar": "solar",
      "birthDate": "1992-08-15",
      "birthTime": "09:30",
      "gender": "male",
      "location": "Shenzhen"
    },
    "messages": [
      {
        "role": "user",
        "content": "Tolong analisis tren keuangan saya tahun ini."
      }
    ]
  }'

Contoh streaming analisis pasangan

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek/deepseek-v3.2",
    "stream": true,
    "locale": "id",
    "topic": "marriage_status",
    "subject_mode": "pair",
    "pair_state": {
      "subjects": [
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1992-08-15",
            "birthTime": "09:30",
            "gender": "male",
            "location": "Shenzhen"
          }
        },
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1995-03-08",
            "birthTime": "22:15",
            "gender": "female",
            "location": "Guangzhou"
          }
        }
      ]
    },
    "messages": [
      {
        "role": "user",
        "content": "Tolong analisis arah jangka panjang hubungan ini dan poin utama kecocokan kami."
      }
    ]
  }'

4. Penagihan dan penanganan error

Aturan kredit dan waktu konfirmasi potongan

Skenario	Aturan
Analisis satu subjek	100 kredit per respons sukses
Analisis pasangan	200 kredit per respons sukses
`need_input`	Tidak dikenakan biaya
Cakupan kredit	Hanya kredit berbayar yang dapat digunakan; bonus pendaftaran dan kredit hadiah tidak berlaku
`stream=true`	Potongan dikonfirmasi saat konten valid pertama yang terlihat dikembalikan
`stream=false`	Potongan dikonfirmasi setelah respons lengkap berhasil dikembalikan
Timeout, gagal, atau respons kosong	Potongan tidak dikonfirmasi atau dikembalikan sesuai aturan yang berlaku

Kode error umum

HTTP Status	Error Code	Deskripsi
`400`	`invalid_messages`	Permintaan tidak memiliki pesan valid atau tidak ada pesan `user`
`400`	`invalid_prompt`	Permintaan tidak menyertakan `messages`, `prompt`, maupun `input`
`400`	`invalid_model`	Model yang diminta tidak ada dalam allowlist saat ini
`401`	`invalid_api_key`	API Key tidak valid atau tidak dikirim
`402`	`insufficient_paid_credits`	Kredit berbayar akun tidak mencukupi
`500`	`request_timeout`	Permintaan habis waktu
`500`	`request_failed`	Permintaan gagal
`500`	`internal_error`	Kesalahan internal server
`502`	`empty_response`	Model tidak mengembalikan konten valid yang terlihat

Respons need_input

Ketika data kelahiran, data topik, atau data pasangan belum lengkap, API dapat mengembalikan respons tipe need_input. Respons ini hanya digunakan untuk melengkapi prasyarat analisis dan tidak dikenakan biaya.