API Pemakaian dan Tagihan

API pemakaian dan tagihan TeamoRouter memungkinkan Anda mengambil pemakaian token dan biaya untuk setiap permintaan model, mengagregasi pemakaian dan tagihan dalam suatu rentang waktu, serta memeriksa saldo akun saat ini.

Ringkasan API

Memulai

Base URL

Gunakan Base URL API yang ditampilkan di konsol TeamoRouter. Contoh di bawah menyebutnya sebagai $TEAMO_BASE_URL:

export TEAMO_BASE_URL="https://teamorouter.com"

Autentikasi

Kirim API key TeamoRouter Anda di header Authorization pada setiap permintaan:

Authorization: Bearer sk-teamo-xxx

Jaga keamanan API key Anda. Jangan menyertakannya di kode frontend, repositori publik, atau log. Semua key dan ID dalam contoh bersifat fiktif.

Mengambil pemakaian dan tagihan untuk satu permintaan

Gunakan ID permintaan untuk mengambil pemakaian token dan biaya akhir dari satu panggilan model.

GET /v1/billing/requests/{request_id}

Parameter path

Contoh permintaan

curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Contoh respons

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1784081234,
  "model": "gpt-5.4",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cached_write_tokens": 800,
    "cached_read_tokens": 200,
    "total_tokens": 2500
  },
  "amount": {
    "value": "0.012680",
    "currency": "USD"
  }
}

Field token

Kategori token yang tidak berlaku atau tidak disediakan oleh layanan upstream mengembalikan 0.

Mengambil tagihan untuk suatu rentang waktu

Ambil total tagihan untuk API key yang terautentikasi dalam suatu rentang waktu. Respons dasar hanya berisi data agregat, bukan catatan per permintaan.

GET /v1/billing/costs

Parameter query

Rentang kueri tidak boleh melebihi 90 hari. Rentang yang lebih panjang mengembalikan 400 invalid_request.

Contoh permintaan

curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Contoh respons

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "total_amount": {
    "value": "1.280000",
    "currency": "USD"
  },
  "requests": 86
}

Mengambil pemakaian token untuk suatu rentang waktu

Ambil agregat pemakaian token untuk API key yang terautentikasi dalam suatu rentang waktu.

GET /v1/usage

Parameter query

Rentang kueri tidak boleh melebihi 90 hari. Rentang yang lebih panjang mengembalikan 400 invalid_request.

Contoh permintaan

curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Contoh respons

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "usage": {
    "input_tokens": 120000,
    "output_tokens": 30000,
    "cached_write_tokens": 10000,
    "cached_read_tokens": 80000,
    "total_tokens": 240000
  },
  "requests": 86
}

Mengambil saldo akun

Ambil saldo yang tersedia untuk akun yang terkait dengan API key saat ini.

GET /v1/billing/balance

Endpoint ini tidak menerima parameter query. API key mengidentifikasi akunnya.

Contoh permintaan

curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Contoh respons

{
  "balance": {
    "value": "85.320000",
    "currency": "USD"
  }
}

Penanganan error

Saat panggilan API gagal, isi respons berisi kode error yang stabil dan pesan yang membantu mendiagnosis masalah.

{
  "error": {
    "code": "invalid_request",
    "message": "end_time must be greater than start_time"
  }
}

Kode error umum

Rekomendasi

• Gunakan start_time dan end_time yang sama saat merekonsiliasi pemakaian dan tagihan agar kedua kueri memakai cakupan yang sama.
• Harga dapat berubah. Gunakan amount yang dikembalikan bersama catatan tagihan historis, jangan menghitung ulang biaya masa lalu dari daftar harga saat ini.
• Konfigurasikan timeout dan percobaan ulang yang wajar. Gunakan exponential backoff untuk respons 429 dan 5xx.