API Documentation

Comprehensive documentation for your Express.js API with versioned routes (Base URL: /api/v1)

Base URL

https://api.ai.nityasha.com/api/v1

Authentication

All endpoints require valid api_key in request body or user authentication via JWT token in Authorization header.

1. Pricing API

Endpoints for managing model pricing information

GET
`/api/v1/pricing`

Get Model Pricing

Fetch pricing information for all active AI models with per 1k and per 1M token costs.

Query Parameters:

Parameter	Type	Required	Description
`model`	string	No	Filter by specific model name

Request Examples:

cURLbash

GET /api/v1/pricing
GET /api/v1/pricing?model=neorox

Response Example (200 OK):

JSON Responsejson

[
  {
    "model_name": "neorox",
    "input_cost_per_1k_tokens": 0.0005,
    "output_cost_per_1k_tokens": 0.0015,
    "input_cost_per_1m_tokens": "0.500000",
    "output_cost_per_1m_tokens": "1.500000"
  },
  {
    "model_name": "gemini-1.5-flash",
    "input_cost_per_1k_tokens": 0.0003,
    "output_cost_per_1k_tokens": 0.0012,
    "input_cost_per_1m_tokens": "0.300000",
    "output_cost_per_1m_tokens": "1.200000"
  }
]

400 - Bad Request

500 - Database error

2. Chat API

Send messages to AI models and receive responses

POST
`/api/v1/chat`

Send Chat Message

Send a message to AI model and get response. Supports streaming and non-streaming modes.

Headers:

Content-Type: application/json

Request Body:

Parameter	Type	Required	Description
`api_key`	string	Yes	Your API key
`messages`	array	Yes	Array of message objects
`model_used`	string	Yes	Model name to use
`stream`	boolean	No	Enable streaming (default: false)
`system_prompt`	string	No	Additional system prompt

Message Object Structure:

{
  "role": "user",
  "content": "Hello, how are you?"
}

Request Example:

{
  "api_key": "your_api_key_here",
  "messages": [
    {
      "role": "user", 
      "content": "What is the weather like today?"
    }
  ],
  "model_used": "neorox",
  "stream": false,
  "system_prompt": "Be helpful and concise"
}

Non-Streaming Response (200 OK):

{
  "object": "chat.completion",
  "model": "neorox",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 45,
    "totalCost": "0.000075"
  },
  "system_prompt": "Be helpful and concise",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I don't have access to real-time weather data. Please check a weather app or website for current conditions."
      }
    }
  ]
}

Streaming Response:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: I don't have access to real-time
data: weather data. Please check a weather
data: app or website for current conditions.
event: done
data: [DONE]

400 - Bad Request

402 - Payment Required

403 - Forbidden

500 - Internal Error

5. Usage Logging

Track and log API usage statistics

POST
`/api/v1/usage/log`

Log API Usage

Manually log API usage (usually done automatically by chat endpoint).

Request Body:

{
  "api_key_id": 456,
  "endpoint_used": "/api/v1/chat",
  "input_tokens": 15,
  "output_tokens": 45,
  "model_used": "neorox"
}

Response (200 OK):

{
  "message": "Usage logged",
  "api_key_id": 456,
  "input_tokens": 15,
  "output_tokens": 45,
  "cost_in_usd": "0.000075",
  "model_used": "neorox"
}

OpenAI Compatibility

Our API is fully compatible with OpenAI's interface. Simply change the base URL to use existing OpenAI SDKs and tools.

Quick Setup

Replace OpenAI's base URL with your custom endpoint to use existing OpenAI code:

Base URL Override

https://api.ai.nityasha.com/api/v1

Node.js (OpenAI SDK)

Installationbash

npm install openai

Usage Examplejavascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.ai.nityasha.com/api/v1", // 👈 Custom base URL
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "neorox",
    messages: [{ role: "user", content: "Hello Neorox!" }],
  });

  console.log(completion.choices[0].message);
}

main();

Python (OpenAI SDK)

Installationbash

pip install openai

Usage Examplepython

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.ai.nityasha.com/api/v1"  # 👈 Custom base URL
)

completion = client.chat.completions.create(
    model="neorox",
    messages=[
        {"role": "user", "content": "Hello Neorox, how are you?"}
    ]
)

print(completion.choices[0].message)

cURL Examples

Non-streaming Requestbash

curl -X POST "https://api.ai.nityasha.com/api/v1/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "neorox",
    "messages": [
      {"role": "user", "content": "Hello Neorox, how are you?"}
    ]
  }'

Streaming Requestbash

curl -N -X POST "https://api.ai.nityasha.com/api/v1/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "neorox",
    "messages": [
      {"role": "user", "content": "Tell me a fun fact"}
    ],
    "stream": true
  }'

OpenAI-Compatible Response Format

{
  "id": "chatcmpl-1725467890123",
  "object": "chat.completion",
  "created": 1725467890,
  "model": "neorox",
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 32,
    "total_tokens": 44,
    "totalCost": "0.000123"
  },
  "system_prompt": null,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm doing great, thanks for asking."
      },
      "finish_reason": "stop"
    }
  ]
}

Migration from OpenAI

To migrate existing OpenAI code to use your API:

Replace your OpenAI API key with your custom API key
Set the baseURL parameter to your domain
Update model names to match your available models (e.g., "neorox", "neorox-pro", etc.)
All other code remains unchanged!

Error Handling

Understanding error responses and status codes

Common Error Response Format

{
  "error": "Error message description",
  "details": "Additional details (in development)"
}

HTTP Status Codes

200Success

400Bad Request (validation error)

401Unauthorized (missing/invalid token)

402Payment Required (insufficient credits)

403Forbidden (invalid API key)

404Not Found

500Internal Server Error

Rate Limiting

Consider implementing rate limiting in production:

Per API key: 100 requests/minute
Per IP: 1000 requests/hour
Chat endpoint: 60 requests/minute

Testing Examples

Using cURL:

# Test pricing endpoint
curl -X GET "https://api.ai.nityasha.com/api/v1/pricing"

# Test chat endpoint
curl -X POST "https://api.ai.nityasha.com/api/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_key_here",
    "messages": [{"role": "user", "content": "Hello"}],
    "model_used": "neorox"
  }'

API Documentation

Base URL

Authentication

1. Pricing API

GET/api/v1/pricing

Get Model Pricing

Query Parameters:

Request Examples:

Response Example (200 OK):

2. Chat API

POST/api/v1/chat

Send Chat Message

Headers:

Request Body:

Message Object Structure:

Request Example:

Non-Streaming Response (200 OK):

Streaming Response:

5. Usage Logging

POST/api/v1/usage/log

Log API Usage

Request Body:

Response (200 OK):

OpenAI Compatibility

Quick Setup

Node.js (OpenAI SDK)

Python (OpenAI SDK)

cURL Examples

OpenAI-Compatible Response Format

Migration from OpenAI

Error Handling

Common Error Response Format

HTTP Status Codes

Rate Limiting

Testing Examples

Using cURL:

GET
`/api/v1/pricing`

POST
`/api/v1/chat`

POST
`/api/v1/usage/log`