CORE · AUTH · PANEL

ChioriyaAPI Docs Utama

Dokumentasi inti platform: autentikasi, sistem limit & refund, endpoint panel (session & apikey), dan Screenshot API. Semua layanan lain (Pixiv, Uploader, Bypass, ChioriyaAI, AmPro, Music) berbagi mekanisme auth dan limit yang sama.

Base URL: deployment Vercel Anda sendiriAuth: session panel / apikeyFormat: JSON + binary gambar

Autentikasi

Panel memakai session login Telegram, sedangkan API publik memakai apikey.

Autentikasi apikey dapat dikirim dengan 4 cara — pilih salah satu:

Metode	Contoh
Query string	`?apikey=KEY_ANDA`
Header	`x-api-key: KEY_ANDA`
Authorization	`Authorization: Bearer KEY_ANDA`
Body JSON (POST)	`{ "apikey": "KEY_ANDA" }`

Cara dapat apikey: hubungkan akun Telegram lewat tombol login di panel, buka Manage Apikey di dashboard, lalu buat / regenerate key. Key utama bisa di-regenerate kapan saja; key lama langsung tidak berlaku.

Sistem Limit & Refund

Ada dua lapis pembatasan: rate-limit IP untuk guest dan limit panel untuk akun tertaut / apikey.

Guest (tanpa login / apikey)

Dibatasi per IP address: 1 request per 30 detik untuk screenshot. Respons membawa header X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, dan saat kena limit Retry-After (HTTP 429).

Akun tertaut / apikey panel

Tanpa cooldown IP. Setiap pemakaian memotong limit panel sesuai biaya layanan (screenshot cost 1, bypass 5–10, AI 1, upload per 512KB). Bila sebuah request gagal diproses, limit otomatis direfund. Sisa limit terlihat di header X-Chioriya-Remaining.

Endpoint Auth

Endpoint session panel. Dipakai oleh tombol login/logout dashboard.

Parameter	Wajib	Default	Keterangan
`/api/auth/start`	-	-	Mulai flow login — mengarahkan ke proses verifikasi Telegram.
`/api/auth/callback`	-	-	Callback login setelah verifikasi; membuat session panel.
`/api/auth/claim`	-	-	Klaim session / tautkan akun ke perangkat.
`/api/auth/me`	-	-	Cek identitas session aktif: guest atau akun tertaut + data limit.
`/api/auth/logout`	-	-	Hapus session panel.
`/api/auth/bridge`	-	-	Bridge session antar subdomain.

Endpoint Apikey Panel

Kelola apikey lewat HTTP langsung — sama persis dengan tombol Manage Apikey di dashboard.

Parameter	Wajib	Default	Keterangan
`/api/panel/apikey/manage`	GET/POST	-	Daftar seluruh apikey milik akun panel.
`/api/panel/apikey/create`	POST	-	Buat apikey baru. Body JSON: nama/label key.
`/api/panel/apikey/delete`	POST	-	Hapus apikey. Body JSON: id key.
`/api/panel/apikey/regenerate`	POST	-	Regenerate apikey utama. Key lama hangus.

Screenshot API — GET /api/screenshot

Screenshot halaman web via Chromium headless: pilih format, viewport, full page, elemen selector, hingga emulasi dark mode.

Parameter	Wajib	Default	Keterangan
`url`	Ya	-	URL target. Harus URL publik (http/https); localhost, IP privat, dan file:// ditolak.
`format / type`	Tidak	webp	webp, jpeg (jpg), atau png.
`quality`	Tidak	80 (webp) / 82 (jpeg)	Kualitas kompresi 10–100. Diabaikan untuk png.
`width / w`	Tidak	1280	Lebar viewport 320–2400 px.
`height / h`	Tidak	720	Tinggi viewport 240–2400 px.
`dpr / scale`	Tidak	1	Device scale factor 1–3 (untuk hasil retina).
`fullPage / full`	Tidak	false	Tangkap seluruh tinggi halaman. Respons Vercel max ±4.5MB.
`mobile`	Tidak	false	Emulasi perangkat mobile (viewport + touch).
`dark`	Tidak	false	Paksa prefers-color-scheme: dark pada target.
`transparent / omitBackground`	Tidak	false	Background transparan (cocok untuk png/webp).
`failOnStatus`	Tidak	false	Gagalkan request bila target balas HTTP error.
`timeout`	Tidak	45000	Timeout navigasi 5000–55000 ms.
`delay / wait`	Tidak	500	Tunggu tambahan 0–5000 ms sebelum capture.
`waitUntil`	Tidak	networkidle2	load \| domcontentloaded \| networkidle0 \| networkidle2.
`selector`	Tidak	-	Screenshot elemen tertentu (CSS selector, max 300 karakter).
`debug`	Tidak	false	Respons error dalam bentuk JSON detail (traceId + tips) alih-alih teks.

Contoh

curl -L -o shot.webp \
  "https://DOMAIN_ANDA/api/screenshot?url=https%3A%2F%2Fapi.chioriya.my.id&format=webp&quality=80&width=1280&height=720"

const res = await fetch('https://DOMAIN_ANDA/api/screenshot?url=' +
  encodeURIComponent('https://api.chioriya.my.id') + '&format=webp&quality=80');
const img = Buffer.from(await res.arrayBuffer());
console.log('bytes:', img.length, 'trace:', res.headers.get('x-screenshot-trace'));

import urllib.request, urllib.parse

q = urllib.parse.urlencode({'url': 'https://api.chioriya.my.id', 'format': 'webp', 'quality': 80})
img = urllib.request.urlopen(f'https://DOMAIN_ANDA/api/screenshot?{q}').read()
open('shot.webp', 'wb').write(img)

Respons

Berhasil → binary gambar langsung (Content-Type image/webp | image/jpeg | image/png) dengan header:

X-Screenshot-Trace: <id-trace>
X-Screenshot-Format: webp
X-RateLimit-Limit: 1            (guest saja)
X-RateLimit-Remaining: 0        (guest saja)
X-Chioriya-Auth: panel          (login / apikey)
X-Chioriya-Remaining: 123       (login / apikey)

Gagal → teks pesan singkat, atau JSON lengkap bila &debug=1 berisi traceId, name, message, runtime, dan array tips saran perbaikan.

Kode Status

Format error konsisten: teks singkat, atau JSON detail dengan &debug=1.

Status	Code	Arti
200	`OK`	Berhasil.
400	`BAD_REQUEST`	Parameter tidak valid / URL tidak diizinkan.
401	`APIKEY_REQUIRED`	Endpoint wajib apikey tapi key tidak terkirim.
403	`PANEL_DENIED / FORBIDDEN`	Apikey tidak valid, limit habis, atau URL diblokir kebijakan keamanan.
404	`NOT_FOUND`	Selector screenshot tidak ditemukan di halaman target.
405	`METHOD_NOT_ALLOWED`	Method salah (misal POST ke endpoint GET).
429	`RATE_LIMITED`	Limit guest tercapai — lihat header Retry-After.
500	`INTERNAL`	Kesalahan runtime; bawa traceId saat melapor.
502	`UPSTREAM_ERROR`	Target mengembalikan HTTP error saat failOnStatus aktif.
504	`TIMEOUT / BYPASS_FAILED`	Target tidak selesai tepat waktu / solver gagal (limit direfund).

Docs Layanan Lain

Dokumentasi lengkap tiap layanan: