Custom API Endpoints - Complete Guide

This document explains all custom API endpoints with authentication, rate limiting, and external service integration.

📚 Table of Contents

Advanced AI Endpoint
External Services Integration
Image Generation & Storage
Text-to-Speech (TTS)
Authentication
Rate Limiting
API Tester Page
Setup Guide

1. Advanced AI Endpoint

Endpoint: POST /api/custom/ai-advanced

Public Base URL

For production usage, use:

Code

https://amadev.org

Features

✅ API Key Authentication
✅ Rate Limiting (10 requests/minute)
✅ Content Filtering
✅ Custom System Prompts
✅ Response Transformation
✅ Metadata Enrichment

Request

Code

const response = await fetch('/api/custom/ai-advanced', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'AMADEV_API_KEY' // Required
  },
  body: JSON.stringify({
    messages: [
      { role: 'user', content: 'Hello, how can you help me?' }
    ],
    options: {
      systemPrompt: 'You are a helpful coding assistant' // Optional
    }
  })
});

const data = await response.json();

2. External Services Integration

Endpoint: POST /api/custom/external-services

Available Services

Weather Service

Code

body: JSON.stringify({
  service: 'weather',
  params: { city: 'Jakarta' }
})

News Service

Code

body: JSON.stringify({
  service: 'news',
  params: { topic: 'technology', limit: 5 }
})

Currency Exchange

Code

body: JSON.stringify({
  service: 'currency',
  params: { from: 'USD', to: 'IDR' }
})

3. Image Generation & Storage

Endpoint: POST /api/creative-studio/generate-image

Features

✅ Proxy to Z.ai Backend
✅ Automatic Download & Local Storage
✅ Base64 & URL Support
✅ Returns local accessible URL

Behavior

When an image is generated, the server automatically:

Intercepts the response from Z.ai
Downloads the binary image data
Saves it to public/generated/
Returns a local URL (e.g., /generated/sunset-1737421234567.jpg)

4. Text-to-Speech (TTS)

Endpoint: POST /api/creative-studio/tts

Features

✅ Proxy to Z.ai Backend
✅ Local Audio Storage
✅ Returns local .mp3 URL

Behavior

Similar to image generation, audio files are saved locally to public/generated/ to ensure persistence and faster loading in the frontend.

5. Authentication

API Key Methods

You can provide API key in two ways:

Method 1: X-API-Key Header (Recommended)

Code

headers: {
  'X-API-Key': 'AMADEV_API_KEY'
}

Method 2: Authorization Bearer

Code

headers: {
  'Authorization': 'Bearer AMADEV_API_KEY'
}

Same API Key for Chat, Image, and Video

The same AMADEV_API_KEY can be used across these endpoints:

POST https://api.amadev.org/v1/chat/completions
GET https://api.amadev.org/v1/models
POST https://api.amadev.org/v1/media/image
POST https://api.amadev.org/v1/media/video
GET https://api.amadev.org/v1/media/video/status?taskId=...

Example image request:

Code

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

Example video request:

Code

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 drone shot flying over tropical cliffs at sunrise","duration":8,"model":"veo-3.0-generate-001"}'

6. Rate Limiting

10 requests per minute per IP address
Resets every 60 seconds
Applies to /api/custom/ai-advanced

Every response includes rate limit headers:

Code

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 2024-01-21T05:30:00.000Z

7. API Tester Page

We have provided a built-in interactive tester to try all endpoints.

URL: http://localhost:3000/api-test

Features:

Select from available endpoints
Interactive JSON body editor
API Key input field
Live Request/Response viewer
Rate limit status display

8. Setup Guide

Step 1: Configure API Keys

Edit .env.local:

Code

API_KEYS=AMADEV_API_KEY,AMADEV_SECONDARY_API_KEY
API_URL=https://...

Step 2: Local Storage

The system automatically creates the public/generated/ directory. Generated files are ignored by git via public/generated/.gitignore.

Step 3: Test with Curl

Code

curl -X POST http://localhost:3000/api/creative-studio/generate-image \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a pixel art cat"}'

🔒 Security Best Practices

Never commit API keys to version control
Use environment variables for all sensitive data
Monitor rate limits to detect abuse
Clean up public/generated/ periodically in production

🆘 Troubleshooting

Problem: "Invalid src prop on next/image"

Solution: Add images.unsplash.com to next.config.ts (already done).

Problem: Endpoint returns 500 Error

Solution: Check server logs. Ensure the Z.ai backend is responsive.

Problem: Rate limit error (429)

Solution: Wait for X-RateLimit-Reset time and retry.