AMADEV API Key Guide

Dokumen ini adalah panduan lengkap untuk halaman admin /admin/apikey, cara membuat API key, dan cara memakai AMADEV_API_KEY untuk endpoint publik di https://api.amadev.org.

1. Ringkasan

Halaman admin API key dipakai untuk:

• membuat API key baru
• membatasi model yang boleh dipakai oleh setiap key
• mengatur rate limit per key
• menonaktifkan atau menghapus key
• melihat penggunaan key terakhir
• melihat analytics request, token, dan latency

Base URL production:

https://amadev.org

2. Lokasi Admin

• Admin menu: /admin/apikey
• Alias lama yang masih dipakai internal page: /admin/llm

File terkait:

• src/app/admin/layout.tsx
• src/app/admin/apikey/page.tsx
• src/app/admin/llm/page.tsx

3. Cara Kerja API Key

Setiap key disimpan di database key dan memiliki properti utama:

• name: nama key untuk admin
• key: nilai rahasia key
• userId: opsional, untuk mengikat key ke user tertentu
• allowedModels: daftar model yang boleh dipakai key itu
• rateLimit: limit request per menit
• isActive: status aktif/nonaktif
• lastUsedAt: terakhir dipakai

Format key yang dihasilkan server memakai prefix:

amallm_

Referensi:

• src/lib/llm/auth.ts
• src/actions/llm.ts

4. Alur Penggunaan dari Admin

4.1. Membuat Key

Di halaman /admin/apikey, klik Create New API Key, lalu isi:

• Key Name
• User (optional)
• Rate Limit (requests/min)
• Allowed Models

Setelah berhasil dibuat:

• key ditampilkan sekali
• admin harus langsung menyalin key itu
• setelah modal ditutup, key tidak ditampilkan penuh lagi

4.2. Mengelola Key

Admin bisa:

• Activate atau Deactivate
• Delete
• melihat user yang terkait
• melihat allowed models
• melihat pemakaian terakhir

4.3. Analytics yang Tersedia

Dashboard analytics menampilkan:

• total requests
• success rate
• total token usage
• average latency
• breakdown per model
• breakdown per API key

Referensi:

• src/app/admin/llm/page.tsx
• src/app/v1/analytics/route.ts

5. Cara Auth ke API

API menerima 2 bentuk auth:

5.1. Header X-API-Key

X-API-Key: AMADEV_API_KEY

5.2. Header Authorization

Authorization: Bearer AMADEV_API_KEY

Implementasi auth:

• server akan cek x-api-key dulu
• kalau kosong, server cek Authorization: Bearer ...
• key harus ada di database dan isActive = true

Referensi:

• src/lib/llm/auth.ts

6. Model yang Saat Ini Didukung

Model global yang tersedia saat ini:

• openai/gpt-oss-120b
• groq/compound
• llama-3.1-8b-instant
• mixtral-8x7b-32768
• gemma2-9b-it
• gemma-7b-it
• llama-3.3-70b-versatile

Catatan:

• setiap key bisa memakai semua model ini, atau subset-nya saja
• jika allowedModels kosong, key mengikuti whitelist global
• metadata model bisa dilihat lewat endpoint /v1/models

Referensi:

• src/lib/amallm-agent.ts
• src/app/v1/models/route.ts

7. Endpoint Publik yang Pakai API Key

7.1. Chat Completions

Endpoint:

POST https://api.amadev.org/v1/chat/completions

Kegunaan:

• OpenAI-compatible chat completion
• support stream
• support tool-calling loop di server

Contoh:

curl -X POST https://api.amadev.org/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: AMADEV_API_KEY" \
  -d '{
    "model": "groq/compound",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

Referensi:

• src/app/v1/chat/completions/route.ts

7.2. List Models

Endpoint:

GET https://api.amadev.org/v1/models

Contoh:

curl https://api.amadev.org/v1/models \
  -H "X-API-Key: AMADEV_API_KEY"

7.3. List Tools

Endpoint:

GET https://api.amadev.org/v1/tools

Opsi:

• ?minimal=1 untuk payload tool yang lebih ringkas

Contoh:

curl "https://api.amadev.org/v1/tools?minimal=1" \
  -H "X-API-Key: AMADEV_API_KEY"

Catatan:

• tool dengan prefix admin. hanya keluar untuk admin

Referensi:

• src/app/v1/tools/route.ts

7.4. Execute Tool Langsung

Endpoint:

POST https://api.amadev.org/v1/tools/execute

Body minimum:

• tool_name
• arguments

Contoh:

curl -X POST https://api.amadev.org/v1/tools/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: AMADEV_API_KEY" \
  -d '{
    "tool_name": "amadev.web.search",
    "arguments": {
      "query": "OpenAI API latest docs"
    }
  }'

Catatan:

• alias toolName dan args juga diterima
• ukuran arguments dibatasi 50KB
• output dipotong jika terlalu besar
• tool admin.* ditolak untuk non-admin

Referensi:

• src/app/v1/tools/execute/route.ts

7.5. Search Query

Endpoint:

POST https://api.amadev.org/v1/search/query

Body:

• query: wajib
• type: web atau academic

Contoh:

curl -X POST https://api.amadev.org/v1/search/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: AMADEV_API_KEY" \
  -d '{
    "query": "latest AI developer tools",
    "type": "web"
  }'

Referensi:

• src/app/v1/search/query/route.ts

7.6. Agent Roundtrip Test

Endpoint:

POST https://api.amadev.org/v1/agent-test/roundtrip

Kegunaan:

• mengetes alur tool-calling 2 langkah
• memverifikasi bahwa model, tool call, tool execution, dan final answer berjalan

Contoh:

curl -X POST https://api.amadev.org/v1/agent-test/roundtrip \
  -H "Content-Type: application/json" \
  -H "X-API-Key: AMADEV_API_KEY" \
  -d '{
    "mode": "simulated",
    "city": "Bangkok",
    "model": "openai/gpt-oss-120b"
  }'

Referensi:

• src/app/v1/agent-test/roundtrip/route.ts

8. Endpoint Media dengan API Key

Wrapper publik ini saya sediakan agar AMADEV_API_KEY bisa dipakai untuk image dan video generation.

8.1. Generate Image

Endpoint:

POST https://api.amadev.org/v1/media/image

Body umum:

• prompt: wajib
• size: opsional, mis. 1:1, 16:9, 9:16
• batch_count: opsional, maksimal 8
• model: opsional, default gemini-2.5-flash-image
• reference_image: opsional
• strength: opsional

Contoh:

curl -X POST https://api.amadev.org/v1/media/image \
  -H "Content-Type: application/json" \
  -H "X-API-Key: AMADEV_API_KEY" \
  -d '{
    "prompt": "cinematic portrait of a futuristic singer on stage",
    "size": "1:1",
    "batch_count": 1
  }'

Response sukses biasanya mengandung:

• success: true
• data.imageUrl
• data.allImages

Referensi:

• src/app/v1/media/image/route.ts
• src/app/api/creative-studio/generate-image/route.ts

8.2. Generate Video

Endpoint:

POST https://api.amadev.org/v1/media/video

Body umum:

• prompt: wajib
• duration: opsional, default 8
• motionIntensity: opsional, default 5
• model: opsional, default veo-3.0-generate-001

Contoh:

curl -X POST https://api.amadev.org/v1/media/video \
  -H "Content-Type: application/json" \
  -H "X-API-Key: AMADEV_API_KEY" \
  -d '{
    "prompt": "a neon-lit city street at night with light rain",
    "duration": 8,
    "model": "veo-3.0-generate-001"
  }'

Response sukses biasanya mengandung:

• success: true
• data.taskId
• data.status
• data.model
• data.originalPrompt
• data.enhancedPrompt jika prompt berhasil diperkaya

Referensi:

• src/app/v1/media/video/route.ts
• src/app/api/creative-studio/generate-video/route.ts

8.3. Check Video Status

Endpoint:

GET https://api.amadev.org/v1/media/video/status?taskId=YOUR_TASK_ID

Contoh:

curl "https://api.amadev.org/v1/media/video/status?taskId=YOUR_TASK_ID" \
  -H "X-API-Key: AMADEV_API_KEY"

Response biasanya mengandung:

• success: true
• data.status: PENDING, SUCCESS, atau FAILED
• data.videoUrl ketika render selesai

Referensi:

• src/app/v1/media/video/status/route.ts
• src/app/api/creative-studio/video-status/route.ts

9. Endpoint Admin yang Dilindungi Role

Beberapa endpoint hanya untuk admin walaupun memakai API key valid.

Contoh:

• GET /v1/admin/audit-logs

Catatan:

• session admin dari dashboard juga bisa dipakai untuk akses UI admin
• untuk API key, role user terkait key harus admin

Referensi:

• src/app/v1/admin/audit-logs/route.ts

10. Contoh Workflow End-to-End

Workflow dasar chat

1. Buat key di /admin/apikey
2. Copy key yang tampil sekali itu
3. Coba GET /v1/models
4. Lanjut POST /v1/chat/completions

Workflow image

1. Siapkan AMADEV_API_KEY
2. Kirim POST /v1/media/image
3. Ambil data.imageUrl

Workflow video

1. Kirim POST /v1/media/video
2. Simpan data.taskId
3. Poll GET /v1/media/video/status?taskId=...
4. Ambil data.videoUrl saat status SUCCESS

11. Error yang Umum

401 Unauthorized

Penyebab umum:

• header key tidak dikirim
• value key salah
• key sudah inactive

403 Forbidden

Penyebab umum:

• key valid tapi mencoba akses endpoint atau tool admin

400 Unsupported model

Penyebab umum:

• model tidak ada di whitelist global
• model tidak masuk allowedModels key tersebut

502 Upstream error

Penyebab umum:

• provider upstream sedang gagal
• tool media atau chat upstream sedang timeout

12. Catatan Implementasi Penting

• update lastUsedAt ditahan agar tidak menulis database setiap request
• error auth yang dikembalikan dibuat generik: Unauthorized
• tool-calling dilakukan oleh server loop, bukan native provider tool calling
• supports_parallel_tool_calls saat ini false

Referensi:

• src/lib/llm/auth.ts
• src/lib/amallm-agent.ts

13. File Referensi Utama

• src/app/admin/llm/page.tsx
• src/actions/llm.ts
• src/lib/llm/auth.ts
• src/lib/amallm-agent.ts
• docs/CUSTOM-API-ENDPOINTS.md