Dokumentasi API

Panduan lengkap untuk memanggil model lewat API Astranesia AI. Semua contoh memakai base URL publik dan ID model publik.

Pengenalan

Astranesia AI menyediakan satu API untuk mengakses berbagai model AI. Format request dan respons kompatibel dengan OpenAI, sehingga SDK yang sudah Anda pakai cukup diarahkan ke base URL berikut.

Base URL

https://www.astranesia.com/v1

Metode	Endpoint	Fungsi
GET	/models	Daftar model yang dapat dipanggil, lengkap dengan harga.
POST	/chat/completions	Percakapan teks, streaming, input gambar, dan tool calling.
POST	/embeddings	Embedding teks.
POST	/systemone	Model keputusan terstruktur, hanya untuk model yang diaktifkan.

Reranking belum tersedia dan endpoint-nya dinonaktifkan sampai antarmuka dan pengukuran penggunaannya terverifikasi. Tidak ada langganan: Anda mengisi saldo Rupiah dan membayar sesuai penggunaan.

Memulai

Buat akun. Pendaftaran gratis.
Isi saldo di menu Saldo & Top-up dengan Virtual Account bank. Saldo masuk setelah pembayaran terkonfirmasi.
Buat API key di menu API Key. Kunci hanya ditampilkan sekali, simpan dengan aman.
Panggil API dengan kunci tersebut seperti contoh di bawah.

curl "https://www.astranesia.com/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      { "role": "system", "content": "Jawab dengan singkat dalam Bahasa Indonesia." },
      { "role": "user", "content": "Halo!" }
    ]
  }'

Autentikasi

Setiap request harus menyertakan API key lewat header Authorization dengan skema Bearer.

Header

Authorization: Bearer sk-astranesia-xxxxxxxxxxxxxxxx

Kunci terikat pada akun Anda. Kunci yang dicabut langsung berhenti berlaku.
Kami hanya menyimpan hash kunci. Jika kunci hilang, buat kunci baru dan cabut yang lama dari dashboard.
Percobaan autentikasi yang gagal berulang dari satu alamat dibatasi sementara dengan status 429 dan kode too_many_auth_failures.

Daftar Model

GET /models mengembalikan model yang dapat dipanggil saat ini. Gunakan nilai id sebagai parameter model. Harga dalam Rupiah per 1 juta token. Katalog lengkap juga ada di halaman Model.

curl "https://www.astranesia.com/v1/models" \
  -H "Authorization: Bearer $AI_API_KEY"

Respons

{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-4.1-mini",
      "object": "model",
      "created": 1767225600,
      "owned_by": "OpenAI",
      "name": "GPT-4.1 mini",
      "type": "chat",
      "context_length": 1047576,
      "max_output_tokens": 32768,
      "capabilities": ["text", "vision", "tools", "streaming", "json_mode"],
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "pricing": {
        "currency": "IDR",
        "input_per_million_tokens": "7920",
        "output_per_million_tokens": "31680",
        "cached_input_per_million_tokens": "1980",
        "per_request": null
      }
    }
  ]
}

Chat Completions

POST /chat/completions menjalankan percakapan. Mendukung pesan system, input gambar pada model yang kompatibel, streaming, dan tool calling bila didukung model. Cek kemampuan setiap model pada halaman modelnya.

curl "https://www.astranesia.com/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      { "role": "system", "content": "Jawab dengan singkat dalam Bahasa Indonesia." },
      { "role": "user", "content": "Halo!" }
    ]
  }'

Respons

{
  "id": "chatcmpl-9f2c1a",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "openai/gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Halo! Ada yang bisa saya bantu?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 11,
    "total_tokens": 35
  }
}

Parameter

Parameter	Tipe	Keterangan
`model`wajib	string	ID model publik, misalnya yang dikembalikan oleh GET /models.
`messages`wajib	array	Percakapan. Role yang didukung: system, developer, user, assistant, dan tool. Konten berupa teks atau array bagian teks dan gambar.
`stream`	boolean	Kirim respons sebagai Server-Sent Events. Hanya untuk model dengan kemampuan streaming.
`stream_options.include_usage`	boolean	Sertakan chunk akhir berisi usage pada stream.
`max_tokens`	integer	Batas token output. Jika kosong, batas default platform diterapkan.
`max_completion_tokens`	integer	Alternatif max_tokens. Nilai di atas batas output model ditolak.
`temperature`	number	0 sampai 2.
`top_p`	number	0 sampai 1.
`stop`	string \| string[]	Hingga 4 urutan penghenti.
`presence_penalty / frequency_penalty`	number	-2 sampai 2.
`seed`	integer	Meminta hasil yang lebih deterministik jika didukung model.
`logit_bias`	object	Peta ID token ke bias -100 sampai 100.
`logprobs / top_logprobs`	boolean / integer	Mengembalikan log probabilitas jika didukung model.
`response_format`	object	text, json_object, atau json_schema. Memerlukan kemampuan JSON mode.
`tools / tool_choice`	array / string \| object	Definisi fungsi dan pilihan pemanggilan. Memerlukan kemampuan tool calling.
`parallel_tool_calls`	boolean	Izinkan beberapa pemanggilan tool dalam satu giliran.
`reasoning_effort`	string	minimal, low, medium, atau high, jika didukung model.
`user`	string	Pengenal opsional untuk pengguna akhir Anda.
`n`	integer	Hanya mendukung nilai 1.

Tool calling

Kirim definisi fungsi pada tools. Jika model memutuskan memanggil fungsi, respons berisi tool_calls. Jalankan fungsi di aplikasi Anda, lalu kirim hasilnya sebagai pesan dengan role tool dan tool_call_id yang sesuai.

curl "https://www.astranesia.com/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [{ "role": "user", "content": "Cuaca di Jakarta?" }],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Ambil cuaca terkini untuk sebuah kota.",
          "parameters": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    ]
  }'

Streaming

Tambahkan stream: true untuk menerima potongan hasil secara langsung sebagai Server-Sent Events. Potongan diteruskan apa adanya tanpa ditahan, termasuk delta tool call. Stream diakhiri dengan data: [DONE].

Penagihan selalu memakai data penggunaan akhir dari model. Jika koneksi Anda terputus di tengah stream, request tetap diselesaikan di sisi server dan ditagih sesuai token yang benar-benar diproses.

curl -N "https://www.astranesia.com/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [{ "role": "user", "content": "Ceritakan tentang Nusantara." }]
  }'

Contoh event

data: {"id":"chatcmpl-9f2c1a","object":"chat.completion.chunk","model":"openai/gpt-4.1-mini","choices":[{"index":0,"delta":{"content":"Halo"}}]}

data: {"id":"chatcmpl-9f2c1a","object":"chat.completion.chunk","model":"openai/gpt-4.1-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-9f2c1a","object":"chat.completion.chunk","model":"openai/gpt-4.1-mini","choices":[],"usage":{"prompt_tokens":24,"completion_tokens":11,"total_tokens":35}}

data: [DONE]

Vision

Untuk model dengan kemampuan Vision, kirim gambar sebagai bagian image_url pada konten pesan user. URL harus memakai https://, atau gunakan data URL base64 untuk png, jpeg, gif, dan webp. Model tanpa kemampuan Vision menolak request dengan vision_not_supported.

curl "https://www.astranesia.com/v1/chat/completions" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Apa yang ada pada gambar ini?" },
          { "type": "image_url", "image_url": { "url": "https://example.com/foto.jpg" } }
        ]
      }
    ]
  }'

Embeddings

POST /embeddings mengubah teks menjadi vektor. input dapat berupa satu teks atau array hingga 2.048 item. Parameter opsional: encoding_format (float atau base64) dan dimensions bila didukung model. Biaya dihitung dari token input.

curl "https://www.astranesia.com/v1/embeddings" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Satu API untuk berbagai model AI."
  }'

Respons

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] }],
  "model": "openai/text-embedding-3-small",
  "usage": { "prompt_tokens": 9, "total_tokens": 9 }
}

System One

POST /systemone menjalankan model keputusan terstruktur. Endpoint ini hanya aktif untuk model yang skema request dan perilaku penagihannya sudah diverifikasi. Isi request mengikuti skema model tersebut dan tidak menerima parameter di luar skema.

Skema dan contoh pemanggilan yang tepat ditampilkan pada halaman setiap model System One di katalog. Jika belum ada model System One yang tercantum, fitur ini belum diaktifkan.

Error Handling

Error dikembalikan sebagai JSON dengan status HTTP yang sesuai. Setiap respons membawa header X-Request-Id; sertakan nilainya saat menghubungi dukungan.

Format error

{
  "error": {
    "message": "Saldo tidak mencukupi untuk request ini. Isi saldo di dashboard lalu coba lagi.",
    "type": "billing_error",
    "param": null,
    "code": "insufficient_credits"
  }
}

HTTP	code	Keterangan
400	`invalid_json`	Isi request bukan JSON yang valid.
400	`invalid_request`	Parameter tidak valid. Kolom param menunjuk ke bidang yang salah.
400	`request_rejected`	Model menolak request. Periksa parameter dan isi pesan.
400	`model_type_mismatch`	Model tidak cocok dengan endpoint yang dipanggil.
400	`streaming_not_supported`	Model tidak mendukung stream: true.
400	`vision_not_supported`	Model tidak menerima input gambar.
400	`invalid_image_url`	URL gambar harus https:// atau data URL base64.
400	`tools_not_supported`	Model tidak mendukung tool calling.
400	`json_mode_not_supported`	Model tidak mendukung response_format JSON.
400	`max_tokens_too_large`	max_tokens melebihi batas output model.
400	`unsupported_parameter`	Parameter tidak didukung, misalnya n selain 1.
400	`embedding_not_supported`	Model tidak mendukung embedding.
400	`system_one_not_supported`	Model tidak mendukung System One.
401	`missing_api_key`	Header Authorization tidak ada.
401	`invalid_api_key`	API key salah atau sudah dicabut.
402	`insufficient_credits`	Saldo tersedia kurang dari perkiraan biaya maksimum request.
403	`account_disabled`	Akun dinonaktifkan.
404	`model_not_found`	Model tidak ada atau belum tersedia lewat API.
413	`payload_too_large`	Ukuran request melebihi batas.
415	`unsupported_content_type`	Content-Type harus application/json.
429	`rate_limit_exceeded`	Batas request per menit tercapai. Perhatikan header Retry-After.
429	`concurrency_limit_exceeded`	Terlalu banyak request yang sedang berjalan.
429	`too_many_auth_failures`	Terlalu banyak percobaan autentikasi yang gagal dari satu alamat. Tunggu sesuai header Retry-After.
429	`model_busy`	Model sedang sibuk. Coba lagi sebentar lagi.
501	`feature_disabled`	Fitur belum diaktifkan, misalnya reranking.
502	`model_error`	Terjadi gangguan pada model.
503	`model_unavailable`	Model sedang tidak tersedia.
503	`service_unavailable`	Layanan inferensi belum tersedia saat ini.
504	`model_timeout`	Model tidak merespons tepat waktu.
500	`internal_error`	Kesalahan internal. Sertakan X-Request-Id saat menghubungi dukungan.

Status 429 dan 5xx bersifat sementara. Ulangi dengan jeda yang bertambah dan hormati header Retry-After.
Request yang gagal sebelum model menghasilkan output tidak dikenai biaya dan saldo yang ditahan dikembalikan.
Batas akun: 60 request per menit dan 5 request bersamaan. Header X-RateLimit-Limit dan X-RateLimit-Remaining menunjukkan sisa jatah.

Pricing & Credits

Satu kredit sama dengan Rp1. Top-up Rp100.000 menjadi saldo Rp100.000. Tidak ada langganan atau biaya bulanan.

Biaya request = token input × harga input + token output × harga output, dibagi 1 juta. Token input tersimpan (cached) memakai harga cached bila model menyediakannya.
Penahanan saldo. Sebelum request diproses, perkiraan biaya maksimum ditahan dari saldo. Setelah selesai, biaya sebenarnya dipotong dan sisanya dikembalikan.
Harga terkunci per request. Perubahan harga tidak memengaruhi request yang sedang berjalan atau tagihan yang sudah tercatat.
Data penggunaan tidak lengkap. Jika model tidak melaporkan token, atau stream dari model terputus setelah mulai menghasilkan output, request ditinjau lebih lanjut dan saldo tetap ditahan sampai selesai. Kami tidak memperkirakan token untuk menentukan tagihan.

Usage

Setiap respons chat dan embedding menyertakan objek usage berisi prompt_tokens, completion_tokens, dan total_tokens. Riwayat lengkap per request, termasuk model, token, biaya, dan waktu, tersedia di menu Penggunaan pada dashboard. Mutasi saldo tercatat di menu Transaksi.

Prompt dan hasil percakapan Anda tidak disimpan di riwayat penggunaan. Yang dicatat hanyalah metadata penagihan.

SDK Examples

Karena kompatibel dengan OpenAI, hampir semua SDK dan kerangka kerja dapat dipakai dengan mengganti base URL dan API key.

Vercel AI SDK

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const provider = createOpenAICompatible({
  name: "astranesia-ai",
  apiKey: process.env.AI_API_KEY,
  baseURL: "https://www.astranesia.com/v1",
});

const { text } = await generateText({
  model: provider("openai/gpt-4.1-mini"),
  prompt: "Jelaskan apa itu API dalam satu kalimat.",
});

console.log(text);

LangChain

Python

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="openai/gpt-4.1-mini",
    api_key=os.environ["AI_API_KEY"],
    base_url="https://www.astranesia.com/v1",
)

print(llm.invoke("Jelaskan apa itu API dalam satu kalimat.").content)