Logo

Complete developer guide and best practices to help you get started quickly.

Keys and headers

Access and authentication

Key-protected endpoints authenticate with the X-API-Key header. This section covers how to obtain a key, how to attach it to a request, and safety advice.

Obtain an API key

  1. Sign in to the developer console.
  2. Open the API keys page.
  3. Click “Create new key” and give the key a label.
  4. Copy and store the key immediately. It is shown only once at creation time and cannot be retrieved again afterwards.

Key scope

A key is bound to the account that created it, and can access that account’s dictionaries and usage quota. Creation, listing, and revocation happen in the console UI; no public management API is exposed.

Attach the key to a request

Path prefix and authentication
Public path
/translations/*
Public access
Look up supported translation languages and models. No API key required — call it directly.
Public path
/audio/*
Public access
Look up supported speech recognition languages and models. No API key required — call it directly.
Private path
/api/v1/*
Requires API key
Pass your key in the X-API-Key header. Keys placed in the query string or body are treated as missing.

Every endpoint under /api/v1 requires X-API-Key in the HTTP header. Do not pass the key in the query string or request body — it will be treated as missing.

HTTP header example

http
X-API-Key: [YOUR_API_KEY]

Full request example (curl)

bash
curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: [YOUR_API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","target_language":"zh-TW"}'

Unauthenticated response

Missing, invalid, or revoked keys return 401 with code = unauthorized. The details object is typically empty — we do not surface why the check failed, to avoid leaking whether the key exists.

401 example

json
{
  "error": {
    "code": "unauthorized",
    "message": "API key is missing or invalid.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

Safety recommendations

Protect your key

Do not embed the key in browser code, mobile app binaries, or public git repositories. Proxy through your own backend and read the key from environment variables there.
  • Issue separate keys per application — easier usage tracking and tighter blast radius.
  • Rotate keys regularly: create the new key, shift traffic, then revoke the old key once stable.
  • If a leak is suspected, revoke the key in the console immediately and create a new one.