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:
Zero code rewrites. Point any standard OpenAI SDK, LangChain agent, or Cursor IDE to https://api.genforai.fun/v1 with your API token.
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.
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:
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.
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.
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.
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.
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
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.
/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)
{
"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
}
}
}
/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 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 |
/v1/models/{id}
Retrieves specific configuration, context length, and capability metadata for a single model.
curl https://api.genforai.fun/v1/models/gpt-5.6-sol \
-H "Authorization: Bearer gfa_live_your_approved_key"
/v1/health
Public, unauthenticated health endpoint for synthetic uptime probes (e.g. BetterStack, UptimeRobot, Datadog). Returns database connectivity status and active upstream route count.
{
"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:
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
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
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
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 Clienthttps://api.genforai.fun/v1