OpenAI Drop-In Compatible REST API • v1.0.0

API Documentation & Architecture Reference

GenForAi provides a high-performance, enterprise-grade AI proxy gateway with native 100% OpenAI SDK compatibility, hardware-bound 2-IP lock defense to eliminate token leakage, and generous 500 RPM burst concurrency.

1. Platform Architecture & Core Principles

#

GenForAi acts as an intelligent intermediary between your client applications (scripts, web backends, Cursor IDE, AI agents) and high-throughput AI inference engines. Designed from the ground up for high-volume developer workloads, the platform enforces three foundational pillars:

1. 100% Drop-In Compatible

Zero code rewrites. Point any standard OpenAI SDK, LangChain agent, or Cursor IDE to https://api.genforai.fun/v1 with your API token.

2. 2-IP Lock Defense

Each key is cryptographically bounded to a maximum of 2 IP addresses. Unauthorized 3rd-party traffic is rejected immediately at the perimeter with HTTP 403.

3. 500 RPM Throughput

Generous 500 requests-per-minute on Free accounts and up to 2,000 RPM on Premium tiers, with 100,000 daily requests and sub-millisecond route dispatch.

2. Quickstart in 60 Seconds

#

Follow these 3 quick steps to send your first chat completion:

1

Create an Account & Request Key

Navigate to Create Account or Log In. Head over to your Developer Console and submit an API Key permission request.

2

Verify Your 2-IP Lock Authorization

Your Primary IP (ip_1) is automatically captured from the workstation you used during key request. If you plan to call the API from an IDE, home server, or cloud VPS, configure your Secondary IP (ip_2) in your Dashboard.

3

Run Your First Request

Replace gfa_live_your_approved_key with your issued token and run the snippet below in your terminal:

curl https://api.genforai.fun/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer gfa_live_your_approved_key" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "user", "content": "Explain closures in JavaScript in 2 concise sentences."}
    ],
    "temperature": 0.7
  }'

3. 2-IP Lock Defense Mechanism

#

Unlike conventional API providers where exposed keys result in catastrophic quota exhaustion and financial liabilities, GenForAi implements a zero-trust hardware IP binding protocol.

Perimeter Hardware Security

Even if your API key is accidentally committed to a public Git repository or logged in terminal output, unauthorized attackers from foreign IP addresses cannot make a single inference call. The gateway automatically halts all requests not originating from your two registered IPs.

Primary IP (ip_1)

Captured and immutably locked at the instant you submit your API key request. This is your primary development workstation or staging server. It cannot be altered without administrator console authorization.

Secondary IP (ip_2)

User-configurable 24/7 directly within your Account Dashboard. Perfect for your cloud VPS, production container, CI/CD runner, or home development laptop.

Your Detected Outbound IP

Manage IPs in Dashboard →
Scanning network... (Use this value as Secondary IP when calling from this device)

4. Base Endpoint & Authentication Specification

#

All API endpoints are served over TLS 1.3 / HTTPS. All client requests must provide the base endpoint and your Bearer authentication token.

https://api.genforai.fun/v1
Authorization: Bearer gfa_live_your_approved_key
POST

/v1/chat/completions

#

Generates a model response for a sequence of conversation messages. Supports both full JSON responses and real-time Server-Sent Events (SSE) streaming token output.

Request Body Parameters

Field Type Requirement Description
model string Required Identifier of the AI model (e.g. gpt-5.6-sol). See List Models for active options.
messages array<object> Required A list of message objects representing the conversation. Each object must have role ("system", "user", or "assistant") and content (string).
stream boolean Optional Defaults to false. When set to true, partial message deltas will be sent as Server-Sent Events (SSE).
temperature number Optional Defaults to 1.0. Sampling temperature between 0.0 (deterministic) and 2.0 (creative).
top_p number Optional Defaults to 1.0. Nucleus sampling probability threshold.
max_tokens integer Optional Maximum number of completion tokens to generate. Bound by the model's context window.
reasoning_effort string Optional For thinking/reasoning models: "low", "medium", or "high". Controls computational reasoning depth.

Code Examples

curl -X POST https://api.genforai.fun/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer gfa_live_your_approved_key" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "system", "content": "You are a senior systems engineer."},
      {"role": "user", "content": "How do goroutines differ from OS threads?"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

Response Schema (Non-Streaming)

HTTP 200 OK — application/json
{
  "id": "chatcmpl-9f8a2b1c4e7d",
  "object": "chat.completion",
  "created": 1792896500,
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Goroutines are lightweight user-space threads managed cooperatively by Go's runtime, whereas OS threads are heavier kernel-managed execution units.",
        "reasoning_content": "The user requested key differences. I need to contrast user-space vs kernel space, memory footprints, and scheduling overhead."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 38,
    "total_tokens": 62,
    "completion_tokens_details": {
      "reasoning_tokens": 28
    }
  }
}
GET

/v1/models

#

Returns a list of all currently active models available on the gateway, their context limits, and capabilities. Models are automatically synchronized every 24 hours from live upstream engines.

cURL Request
curl https://api.genforai.fun/v1/models \
  -H "Authorization: Bearer gfa_live_your_approved_key"

Live Synced Model Roster

Model Identifier Tier Access Context Window Extended Reasoning Protocol Support
gpt-5.6-sol Free & Unlimited 128,000 tokens Standard Chat, Streaming, Responses
gpt-6-astra Premium 128,000 tokens Standard Chat, Streaming, Responses
gpt-6.1-sol Premium 128,000 tokens Standard Chat, Streaming, Responses
GET

/v1/models/{id}

#

Retrieves specific configuration, context length, and capability metadata for a single model.

cURL Request
curl https://api.genforai.fun/v1/models/gpt-5.6-sol \
  -H "Authorization: Bearer gfa_live_your_approved_key"
GET

/v1/health

#

Public, unauthenticated health endpoint for synthetic uptime probes (e.g. BetterStack, UptimeRobot, Datadog). Returns database connectivity status and active upstream route count.

HTTP Response Sample (No Token Required)
{
  "status": "operational",
  "service": "GenForAi",
  "version": "1.0.0",
  "environment": "production",
  "database": "connected",
  "database_driver": "mysql",
  "active_models": 3,
  "timestamp": 1794050485
}

5. Real-Time Streaming (SSE) & Reasoning

#

When stream: true is passed in the request body, GenForAi immediately establishes a text/event-stream Server-Sent Events channel. The connection bypasses Apache proxy buffers via X-Accel-Buffering: no, delivering sub-15ms first-token latency.

Extended Reasoning & Thinking Tokens

Models equipped with reasoning capabilities output their internal thinking chain via delta.reasoning_content before generating final text:

SSE Chunk Protocol Format
data: {"id":"chatcmpl-a1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

# Reasoning stream chunk
data: {"id":"chatcmpl-a1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"Step 1: Compute time complexity...\n"},"finish_reason":null}]}

# Final content stream chunk
data: {"id":"chatcmpl-a1","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"The algorithm runs in O(N log N) time."},"finish_reason":null}]}

# Terminal signal
data: [DONE]

6. SDKs & Tool Integrations

#

Because GenForAi adheres 100% to the official OpenAI REST specification, you can drop our endpoint into any standard library or IDE without custom adapters.

Python OpenAI SDK (Official)

Install via pip: pip install openai

from openai import OpenAI

# Initialize client pointing to GenForAi
client = OpenAI(
    base_url="https://api.genforai.fun/v1",
    api_key="gfa_live_your_approved_key"
)

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Stream a short haiku about compilers."}],
    stream=True
)

for chunk in stream:
    text = chunk.choices[0].delta.content or ""
    print(text, end="", flush=True)

Node.js & TypeScript SDK

Install via npm: npm install openai

TypeScript / ESM
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://api.genforai.fun/v1',
  apiKey: 'gfa_live_your_approved_key',
});

const stream = await openai.chat.completions.create({
  model: 'gpt-5.6-sol',
  messages: [{ role: 'user', content: 'Explain asynchronous event loops.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Cursor IDE & VS Code AI Extensions

C

Cursor IDE Configuration

Open Cursor → Settings → Models → Enable OpenAI API Key:

  • Override OpenAI Base URL: https://api.genforai.fun/v1
  • API Key: gfa_live_your_approved_key
  • Model Name: gpt-5.6-sol

LangChain & LiteLLM

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.6-sol",
    openai_api_base="https://api.genforai.fun/v1",
    openai_api_key="gfa_live_your_approved_key",
    temperature=0.7
)

response = llm.invoke("Explain quantum entanglement.")
print(response.content)

cURL & Raw HTTP Requests

Shell / Bash
curl -X POST https://api.genforai.fun/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer gfa_live_your_approved_key" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Ping"}],
    "temperature": 0.7
  }'

7. Rate Limits & Concurrency Specifications

#

GenForAi uses sliding-window in-memory and database rate-limiting to prevent noisy neighbors and ensure smooth service availability for all developers:

Account Tier Requests Per Minute (RPM) Daily Request Quota (RPD) Concurrency
Free Tier 500 RPM 100,000 / day High concurrency
Premium Tier 2,000 RPM 1,000,000 / day Ultra-high dedicated priority
Standard Rate Limit Response Headers

Every response includes X-RateLimit-Limit-Requests-Minute and X-RateLimit-Remaining-Requests-Minute headers so your client can dynamically throttle if approaching bounds.

8. HTTP Status Codes & Resolution Matrix

#

All API error responses return standard JSON conforming to the OpenAI error envelope: {"error": {"message": "...", "type": "...", "code": "..."}}.

Status Error Type Root Cause Step-by-Step Resolution
400 Bad Request invalid_request_error Malformed JSON, missing messages array, or empty model parameter. Verify your request payload structure and ensure Content-Type: application/json is present.
401 Unauthorized authentication_error Missing, inactive, or malformed API Bearer key. Check your Authorization: Bearer ... header. Verify that your key is marked approved in your Dashboard.
403 Forbidden ip_unauthorized Outbound IP does not match the key's 2 registered IP slots (ip_1 or ip_2). Navigate to Dashboard and enter your current IP (detected as ...) into the Secondary IP (IP 2) field.
403 Forbidden premium_required Attempted to call a Premium model using a Free tier account. Upgrade to Premium via our official Discord Community, or switch your request to an active free tier model.
404 Not Found model_not_found The requested model name does not exist on the platform. Query GET /v1/models to verify active model IDs.
429 Rate Limit rate_limit_error Exceeded 500 requests per minute or daily quota. Implement exponential backoff retry in your client or upgrade to Premium for 2,000 RPM.
503 Unavailable service_unavailable No AI models currently synchronized. Trigger model sync in the Administrator console or retry in 60 seconds.
504 Timeout gateway_timeout Upstream reasoning engine took longer than 120s to respond. Enable streaming (stream: true) or reduce token output limit.

9. Live Interactive API Request Builder & Tester

#

Test real endpoints right in your browser. Configure parameters below to generate live cURL syntax, inspect headers, and execute requests directly against the gateway:

Live Request Builder

Browser Client

                    
Testing against: https://api.genforai.fun/v1
ESC