API Documentation

Request examples, authentication, and response formats for the Zydra API.

1. Authentication

Include an API key with every request to a model endpoint. Create and manage your keys on the API Keys page. Pass the key in a header or as a query parameter:

Authorization Header

Authorization: Bearer ...

Header (x-api-key)

x-api-key: zydra_live_...

URL Parameter

?apikey=zydra_live_...

2. Endpoints

GET / POST/api/v1/prompt

Sends your prompt to the Zydra model and returns the generated text. Each user has a shared daily allowance of 150,000 tokens across all API keys. Both input and generated output tokens count; the allowance resets at 00:00 UTC.

Example Response (200 OK)

// Example successful response (200 OK)
{
  "model": "zydra-lora",
  "response": "My name is Zydra. I was created by Farel Alfareza (Fareldev).",
  "creator": "Farel Alfareza",
  "latency_ms": 1420,
  "token_usage": {
    "limit": 150000,
    "used": 236,
    "remaining": 149764,
    "resetsAt": "2026-11-09T00:00:00.000Z"
  },
  "token_usage_details": {
    "input_tokens": 12,
    "output_tokens": 224,
    "estimated": true
  },
  "key_info": {
    "name": "Production App",
    "prefix": "zydra_live_f9f...220e",
    "usage_count": 5
  },
  "timestamp": "2026-11-08T05:25:20.000Z"
}

Example Response (504 Gateway Timeout)

// If the model service is unavailable, the API returns a non-200 HTTP status
{
  "error": {
    "code": "gateway_timeout",
    "message": "AI upstream timed out",
    "upstream_status": 200
  },
  "latency_ms": 280
}

Example Response (429 Too Many Requests)

// The API returns 429 when the daily token allowance is exhausted
{
  "error": {
    "code": "daily_token_limit_exceeded",
    "message": "Your daily token allowance is used up. It will reset at the time shown."
  },
  "token_usage": {
    "limit": 150000,
    "used": 150000,
    "remaining": 0,
    "resetsAt": "2026-11-09T00:00:00.000Z"
  }
}

GET/api/v1/status

Checks whether the model service is reachable and returns its current status.

3. Code Examples

cURL Example

# 1. Send a prompt with GET
curl -X GET "https://your-domain.com/api/v1/prompt?apikey=YOUR_KEY&prompt=Who+are+you%3F"

# 2. Send a prompt with POST JSON
curl -X POST "https://your-domain.com/api/v1/prompt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"prompt": "Who are you?"}'

# 3. Check service status
curl -X GET "https://your-domain.com/api/v1/status"

Image Vision Example

Send a publicly accessible image URL with a caption to analyze it.

cURL Vision Example

# Replace the URL with a publicly accessible image
curl -X POST "https://your-domain.com/api/v1/chat/vision" \
  -H "Content-Type: application/json" \
  -H "x-api-key: zydra_live_YOUR_KEY" \
  -d '{"image_link":"https://example.com/image.jpg","caption":"Describe this image"}'