Konvensi Umum V1 API

Autentikasi, penagihan, objek bersama, dan format respons error untuk V1 Open API

Dokumen ini menjelaskan autentikasi, penagihan, objek bersama, dan format respons error untuk V1 Open API (/v1/*).

Cakupan: Endpoint Relay /v1 publik — total 12.

Konvensi umum

Base URL

http://www.mangoto.ai

Endpoint dipasang di root domain, mis. POST http://www.mangoto.ai/v1/chat/completions.

Autentikasi

Semua endpoint /v1 publik menggunakan Bearer Token:

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

Aturan	Deskripsi
Validasi token	Memvalidasi API Key, status pengguna, dan saldo/kuota
Allowlist IP	Jika token memiliki allowlist IP, sumber permintaan diperiksa
Override channel	Admin dapat menambahkan `-{channelId}` setelah Key (mis. `sk-xxx-6`); pengguna biasa tidak dapat
Kegagalan auth	Mengembalikan HTTP `401` / `403`

Pengecualian: GET /v1/videos/{task_id}/content mendukung Session konsol admin dan Bearer Token.

Content-Type

Skenario	Content-Type
Permintaan JSON	`application/json`
Edit gambar / buat video dengan file	`multipart/form-data`
Respons TTS	`audio/mpeg`, `audio/wav`, dll. (tergantung `response_format`)
Streaming Chat / Responses	`text/event-stream` (SSE)

Penagihan

Gateway memilih channel upstream secara otomatis berdasarkan model di body permintaan (atau parameter path)
Mendukung penagihan berbasis token, per permintaan, per detik, dan strategi lainnya
API Key yang berbeda mungkin melihat daftar model yang berbeda

Objek respons bersama

`usage` (penagihan token)

Umum di respons endpoint teks (Chat / Completions / Responses):

Field	Tipe	Deskripsi
`prompt_tokens`	integer	Jumlah token input (Completions / Chat)
`completion_tokens`	integer	Jumlah token output (Completions / Chat)
`total_tokens`	integer	Total jumlah token
`input_tokens`	integer	Jumlah token input (Responses)
`output_tokens`	integer	Jumlah token output (Responses)
`prompt_cache_hit_tokens`	integer	Token input yang di-cache (beberapa model)
`prompt_tokens_details`	object	Rincian token input
`prompt_tokens_details.cached_tokens`	integer	Jumlah token yang di-cache
`prompt_tokens_details.text_tokens`	integer	Jumlah token teks
`prompt_tokens_details.audio_tokens`	integer	Jumlah token audio
`prompt_tokens_details.image_tokens`	integer	Jumlah token gambar
`completion_tokens_details`	object	Rincian token output
`completion_tokens_details.reasoning_tokens`	integer	Jumlah token reasoning
`completion_tokens_details.text_tokens`	integer	Jumlah token teks

`usage` (penagihan per permintaan, gambar)

Field	Tipe	Deskripsi
`quota_type`	integer	Pengenal jenis penagihan
`quota`	integer	Kuota yang dikonsumsi oleh permintaan ini
`request_count`	integer	Jumlah permintaan, biasanya 1
`prompt_tokens`	integer	Token input (biasanya 0 untuk endpoint gambar)
`completion_tokens`	integer	Token output (biasanya 0 untuk endpoint gambar)
`total_tokens`	integer	Total token (biasanya 0 untuk endpoint gambar)

Respons error

Error standar (teks / gambar / audio / konten video)

Kode status HTTP: 400, 401, 403, 404, 429, 500, dll.

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "model"
  }
}

Field	Tipe	Deskripsi
`error.message`	string	Deskripsi error yang dapat dibaca manusia
`error.type`	string	Jenis error, mis. `invalid_request_error`, `insufficient_quota`
`error.code`	string	Kode error, mis. `invalid_request`, `model_not_found`
`error.param`	string	Field permintaan yang menyebabkan error (jika ada)
`error.metadata`	object	Metadata diperluas (dikembalikan beberapa upstream)

Error tugas (pembuatan / kueri tugas video gagal)

Kode status HTTP: 400, 429, dll.

{
  "code": "invalid_request",
  "message": "model is required"
}

Field	Tipe	Deskripsi
`code`	string	Kode error; umumnya `invalid_request`
`message`	string	Deskripsi error

Pada HTTP 429, message adalah: 当前分组上游负载已饱和，请稍后再试 (beban upstream untuk grup saat ini sudah jenuh; coba lagi nanti).

Error diperluas gateway (daftar model, daftar suara, dll.)

Kode status HTTP: 200 (kegagalan bisnis) atau 400.

{
  "success": false,
  "message": "get user group failed"
}

Field	Tipe	Deskripsi
`success`	boolean	Apakah panggilan berhasil; `false` berarti gagal
`message`	string	Deskripsi error

Saldo token & detail penggunaan

Authentication matches other /v1 APIs: Authorization: Bearer sk-xxxxxxxx. Only the current Bearer token's data can be queried.

Metode	Path	Deskripsi
GET	`/v1/token/balance`	Kueri saldo token (⚡)
GET	`/v1/token/consume`	Query current API Key consume records (paginated)

Autentikasi: Authorization: Bearer sk-xxxxxxxx

curl http://www.mangoto.ai/v1/token/balance \
  -H "Authorization: Bearer sk-xxxxx"

Body respons

HTTP 200

{
  "success": true,
  "message": "",
  "data": {
    "id": 1,
    "name": "API Token",
    "remain_quota_usd": 0.2,
    "used_quota_usd": 0.1,
    "unlimited_quota": false
  }
}

Field respons

Field	Tipe	Deskripsi
`success`	boolean	Apakah panggilan berhasil
`message`	string	Pesan status
`data.id`	integer	ID token
`data.name`	string	Nama token
`data.remain_quota_usd`	number	Kuota tersisa (⚡). Selalu `0` untuk token tak terbatas
`data.used_quota_usd`	number	Kuota terpakai (⚡)
`data.unlimited_quota`	boolean	Apakah token memiliki kuota tak terbatas

GET `/v1/token/consume`

Paginated consume records for the current Bearer API Key only (token_id, type=consume). Not the owning user's wallet logs.

Autentikasi: Authorization: Bearer sk-xxxxxxxx

Parameter permintaan

Parameter	Tipe	Wajib	Deskripsi
`page`	integer	Tidak	Nomor halaman, default `1`
`page_size`	integer	Tidak	Item per halaman, default `10`, maksimum `100`
`time_range`	string	Tidak	Filter rentang waktu cepat; hanya `all`, `today`, `yesterday`, `week`, `month` yang diizinkan. Prioritas lebih tinggi daripada `start_timestamp` / `end_timestamp`
`start_timestamp`	integer	Tidak	Timestamp mulai (digunakan saat `time_range` kosong)
`end_timestamp`	integer	Tidak	Timestamp akhir (digunakan saat `time_range` kosong)
`model_name`	string	Tidak	Filter nama model
`request_id`	string	Tidak	Filter ID permintaan
`upstream_request_id`	string	Tidak	Filter ID permintaan upstream

Contoh permintaan (curl)

curl "http://www.mangoto.ai/v1/token/consume?page=1&page_size=10&time_range=today" \
  -H "Authorization: Bearer sk-xxxxx"

Body respons

HTTP 200

{
  "success": true,
  "message": "",
  "code": 0,
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 100,
    "items": [
      {
        "id": 1,
        "created_at": 1700000000,
        "type": 2,
        "type_name": "",
        "content": "",
        "token_name": "default",
        "model_name": "gpt-3.5-turbo",
        "app_name": "",
        "usage_name": "gpt-3.5-turbo",
        "quota_usd": 0.002,
        "quota_type": 2
      }
    ]
  }
}

Field respons

Field	Tipe	Deskripsi
`success`	boolean	Apakah panggilan berhasil
`message`	string	Pesan status
`code`	integer	Kode status; `0` = sukses, `-1` = kegagalan bisnis
`data.page`	integer	Nomor halaman saat ini
`data.page_size`	integer	Item per halaman
`data.total`	integer	Total jumlah catatan
`data.items`	array	Daftar entri detail penggunaan
`data.items[].id`	integer	ID log
`data.items[].created_at`	integer	Timestamp pembuatan
`data.items[].type`	integer	always `2` (consume)
`data.items[].type_name`	string	consume
`data.items[].content`	string	Konten log
`data.items[].token_name`	string	Nama token
`data.items[].model_name`	string	Nama model
`data.items[].app_name`	string	Nama aplikasi (jika dari aplikasi Apps)
`data.items[].usage_name`	string	Nama model yang digunakan, atau nama aplikasi Apps
`data.items[].quota_usd`	number	Perubahan kuota (⚡);
`data.items[].quota_type`	integer	Tipe perubahan kuota (`0` tidak ada, `1` peningkatan, `2` penurunan)

Dokumentasi terkait

Glosarium

Konsep, field, dan istilah error umum yang digunakan dalam dokumentasi bantuan

API Model

Daftar model yang terlihat oleh API Key dan jenis endpoint yang didukung setiap model