API Reference
Genfity AI Gateway provides a single endpoint compatible with standard chat completions (OpenAI) and Messages API (Anthropic) formats to access all AI models. Just change the base URL and use your Genfity API key.
| BASE URL (OpenAI) | https://ai.genfity.com/v1 |
| BASE URL (Anthropic) | https://ai.genfity.com |
Quick start
curl https://ai.genfity.com/v1/models \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx"Authentication
All requests require an API key sent via the Authorization header. Get your API key at Dashboard → API Keys.
| Header | Type | Description |
|---|---|---|
| Authorization | string required | API Key in Bearer <api_key> format. Get it from the dashboard. |
curl https://ai.genfity.com/v1/chat/completions \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"genfity/claude-opus-4.7","messages":[{"role":"user","content":"Hello"}]}'Endpoints
Send requests to any AI model through the following endpoints.
Create Chat Completion (OpenAI)
/v1/chat/completions
Send an OpenAI-compatible chat completion request to any AI model in the Genfity catalog.
Headers
| Authorization | string required | API Key in Bearer <api_key> format. |
| Content-Type | string required | Must be application/json. |
Request Body
| model | string required | Model ID from catalog. See /v1/models. |
| messages | array required | Array of message objects with role and content. |
| stream | boolean | Enable SSE streaming. Default false. |
| max_tokens | integer | Maximum output tokens. |
| temperature | number | Sampling temperature (0-2). |
| top_p | number | Nucleus sampling (0-1). |
| tools | array | OpenAI-format tool calling definitions. |
| response_format | object | Output format, e.g. { type: json_object }. |
curl -X POST https://ai.genfity.com/v1/chat/completions \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "genfity/claude-opus-4.7",
"messages": [
{ "role": "user", "content": "Apa ibukota Indonesia?" }
],
"temperature": 0.7,
"max_tokens": 256,
"stream": false
}'{
"id": "chatcmpl_01Hxx...",
"object": "chat.completion",
"created": 1778803200,
"model": "genfity/claude-opus-4.7",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Ibukota Indonesia adalah Jakarta."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 8,
"total_tokens": 22
}
}Anthropic Messages
/v1/messages
Send an Anthropic-compatible request to any AI model. Suitable for Claude SDKs and tools requiring Messages API.
Headers
| Authorization | string required | API Key in Bearer <api_key> format. |
| Content-Type | string required | Must be application/json. |
Request Body
| model | string required | Model ID from catalog. |
| max_tokens | integer required | Maximum output tokens. |
| messages | array required | Array of messages with role and content. |
| system | string | System prompt (optional). |
| stream | boolean | Enable SSE streaming. |
| tools | array | Tool definitions with input_schema. |
| tool_choice | object | Control which tool is called. |
curl -X POST https://ai.genfity.com/v1/messages \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "genfity/claude-opus-4.7",
"max_tokens": 1024,
"messages": [
{ "role": "user", "content": "Hello Genfity" }
]
}'{
"id": "msg_01Hxx...",
"type": "message",
"role": "assistant",
"model": "genfity/claude-opus-4.7",
"content": [
{ "type": "text", "text": "Hello! How can I help you today?" }
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 25,
"output_tokens": 12
}
}Count Tokens
/v1/messages/count_tokens
Estimate the number of tokens in a prompt before sending a generation request.
Headers
| Authorization | string required | API Key in Bearer <api_key> format. |
Request Body
| model | string required | Model ID from catalog. |
| messages | array required | Messages to count. |
curl -X POST https://ai.genfity.com/v1/messages/count_tokens \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "genfity/claude-opus-4.7",
"messages": [{"role":"user","content":"Count this text"}]
}'{
"input_tokens": 12
}Embeddings
/v1/embeddings
Generate vector embeddings from input text. Only available for embedding models in the catalog.
Headers
| Authorization | string required | API Key in Bearer <api_key> format. |
Request Body
| model | string required | Embedding model ID from catalog. |
| input | string | array required | Text or array of texts to embed. |
curl -X POST https://ai.genfity.com/v1/embeddings \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "genfity/claude-opus-4.7",
"input": "Genfity AI Gateway makes AI integration simple."
}'{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.0023, -0.0091, 0.0042, ...]
}
],
"model": "genfity/claude-opus-4.7",
"usage": { "prompt_tokens": 8, "total_tokens": 8 }
}Image Generation
/v1/images/generations
Generate images from text prompts using image generation models like GPT Image, FLUX, Stable Diffusion, and more.
Headers
| Authorization | string required | API Key in Bearer <api_key> format. |
| Content-Type | string required | Must be application/json. |
Request Body
| model | string required | Image model ID, e.g. openai/gpt-image-2, together/black-forest-labs/FLUX.2-pro, flux-kontext. |
| prompt | string required | Description of the image to generate. |
| n | integer | Number of images (default 1). |
| size | string | Image size, e.g. 1024x1024, 1024x1792. |
| quality | string | Quality: standard or hd. |
| response_format | string | Output format: url or b64_json. |
curl -X POST https://ai.genfity.com/v1/images/generations \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-image-2",
"prompt": "A beautiful sunset over Indonesian rice terraces",
"n": 1,
"size": "1024x1024"
}'{
"created": 1778803200,
"data": [
{
"url": "https://...",
"revised_prompt": "A beautiful sunset over Indonesian rice terraces"
}
]
}List Models
/v1/models
Get a list of all models available to your account.
Headers
| Authorization | string required | API Key in Bearer <api_key> format. |
curl https://ai.genfity.com/v1/models \
-H "Authorization: Bearer genfity_xxxxxxxxxxxx"{
"object": "list",
"data": [
{ "id": "genfity/claude-opus-4.7", "object": "model", "owned_by": "genfity" }
]
}Model & Pricing
Supported models and pricing per 1M tokens. Data is fetched directly from the active catalog database.
Loading models from database...
Error Codes
Genfity AI Gateway uses standard HTTP status codes.
| Code | Message | Meaning |
|---|---|---|
| 400 | invalid_json | Body is not valid JSON. |
| 400 | missing_model | Model field is empty. |
| 400 | model_not_allowed | Model not found or inactive in catalog. |
| 400 | max_tokens_required | PAYG/credit requires max_tokens limit. |
| 401 | missing_api_key | Authorization header is empty. |
| 401 | invalid_api_key_format | Header is not a Bearer token. |
| 401 | invalid_api_key | Key is invalid or revoked. |
| 402 | no_active_subscription | Key has no active subscription. |
| 402 | subscription_not_covering_model | Plan does not cover this model. |
| 402 | credit_cost_not_configured | Model has no credit cost configured. |
| 402 | payg_price_not_configured | Model has no PAYG price configured. |
| 402 | insufficient_credit_balance | Insufficient credit balance. |
| 402 | insufficient_balance | Insufficient balance. |
| 403 | forbidden | No access to this model. |
| 429 | rate_limit_exceeded | RPM/TPM/concurrency limit exceeded. |
| 429 | quota_exceeded | Period token quota exhausted. |
| 429 | global_rate_limit_exceeded | IP burst guard exceeded. |
| 500 | internal_error | Internal gateway error. |
| 502 | router_unavailable | The model/provider is under high traffic. Try again later. |
| 502 | upstream_error | The model/provider is under high traffic. Try again later. |
| 502 | all_candidates_failed | The model/provider is under high traffic. Try again later. |
| 503 | service_unavailable | Service is under maintenance. |
Rate Limits
Request limits are set per API key from Dashboard → API Keys. When limits are exceeded, the API returns 429 Too Many Requests.
- •
rate_limit_per_min— Requests per minute per key - •
quota_tokens_monthly— Monthly token quota - •
concurrent_limit— Concurrent requests
- • Window: 1 minute
- • Scope: IP + endpoint path
- • Error:
global_rate_limit_exceeded
IDE & Editor
Genfity AI Gateway uses OpenAI-compatible and Anthropic-compatible formats, so almost any IDE, CLI, or SDK that supports custom base URLs works out of the box. Just change the base URL and use your Dashboard API key.
Cline
Autonomous coding agent for VS Code
Cline supports OpenAI Compatible providers. Fill in base URL, API key, and model ID in the Settings panel.
- 1Install the Cline extension from VS Code Marketplace.
- 2Open the Cline panel (left sidebar), click the Settings icon.
- 3API Provider → choose OpenAI Compatible.
- 4Fill the fields according to the snippet, click Done.
API Provider = OpenAI Compatible
Base URL = https://ai.genfity.com/v1
API Key = genfity_xxxxxxxxxxxx
Model ID = genfity/claude-opus-4.7Roo Code
Cline fork with multi-mode agents
Roo Code (Cline fork) uses the same configuration — choose OpenAI Compatible then fill the Genfity base URL and key.
- 1Install the Roo Code extension from VS Code Marketplace.
- 2Open the Roo Code panel, click Settings or profile name.
- 3API Provider: OpenAI Compatible (not OpenAI).
- 4Save the profile, pick a mode (Code/Architect/Ask) and start prompting.
API Provider = OpenAI Compatible
Base URL = https://ai.genfity.com/v1
API Key = genfity_xxxxxxxxxxxx
Model ID = genfity/claude-opus-4.7Continue.dev
Autopilot for VS Code & JetBrains
Continue uses ~/.continue/config.yaml to declare providers. Add an openai-compatible entry with the Genfity apiBase.
- 1Install the Continue extension in VS Code / JetBrains.
- 2Open ~/.continue/config.yaml (Continue: Open Config).
- 3Add a Genfity model under the models key.
- 4Reload — the model will appear in Continue's chat dropdown.
models:
- name: Genfity Claude Opus
provider: openai
model: genfity/claude-opus-4.7
apiBase: https://ai.genfity.com/v1
apiKey: genfity_xxxxxxxxxxxx
roles:
- chat
- edit
- applyCursor
AI-native code editor
Cursor supports Override OpenAI Base URL at Settings → Models. Enable OpenAI API Key, then point base URL to Genfity.
- 1Cursor Settings → Models → scroll to OpenAI API Key.
- 2Enter API key: genfity_xxxxxxxxxxxx.
- 3Expand section → enable Override OpenAI Base URL.
- 4Set base URL: https://ai.genfity.com/v1. Click Verify.
- 5Enable only models available in the Genfity catalog.
OpenAI API Key = genfity_xxxxxxxxxxxx
Override Base URL = https://ai.genfity.com/v1
Enabled Models = genfity/claude-opus-4.7, ...Windsurf (Codeium)
Agentic IDE by Codeium
Windsurf Cascade supports custom model endpoints. Add an OpenAI-compatible provider via Settings → Cascade → Add Custom Model.
- 1Settings (Cmd/Ctrl + ,) → Cascade → Models.
- 2Add Custom Model → choose OpenAI protocol.
- 3Fill Base URL + Genfity API Key + Model ID.
- 4Enable the new model and start a Cascade session.
Protocol = OpenAI
Endpoint = https://ai.genfity.com/v1
API Key = genfity_xxxxxxxxxxxx
Model ID = genfity/claude-opus-4.7
Display Name = Genfity Claude OpusZed
High-performance collaborative editor
Zed supports OpenAI API Compatible providers via settings.json. Add Genfity as a custom provider, then store the API key through Agent Panel settings.
- 1Zed → Cmd/Ctrl + , → open settings.json.
- 2Add the language_models.openai_compatible key as in the snippet.
- 3Open Agent Panel settings (Cmd/Ctrl + Shift + P → agent: open settings).
- 4Find the "Genfity AI Gateway" provider, paste your API key, press Enter.
- 5Select a Genfity model from the Agent Panel model dropdown.
{
"language_models": {
"openai_compatible": {
"Genfity AI Gateway": {
"api_url": "https://ai.genfity.com/v1",
"available_models": [
{
"name": "genfity/auto",
"display_name": "Genfity Auto (Combo)",
"max_tokens": 200000,
"capabilities": {
"tools": true,
"images": true
}
},
{
"name": "genfity/claude-opus-4.7",
"display_name": "Genfity Claude Opus 4.7",
"max_tokens": 200000,
"capabilities": {
"tools": true,
"images": true
}
},
{
"name": "genfity/claude-haiku-4.5",
"display_name": "Genfity Claude Haiku 4.5",
"max_tokens": 200000,
"capabilities": {
"tools": true,
"images": true
}
}
]
}
}
},
"agent": {
"default_model": {
"provider": "openai_compatible",
"model": "genfity/auto"
}
}
}CLI & Terminal
Genfity AI Gateway uses OpenAI-compatible and Anthropic-compatible formats, so almost any IDE, CLI, or SDK that supports custom base URLs works out of the box. Just change the base URL and use your Dashboard API key.
Claude Code
Anthropic's official CLI
Claude Code uses the Anthropic-compatible endpoint. Set the ANTHROPIC_BASE_URL environment variable to Genfity.
- 1Install: npm install -g @anthropic-ai/claude-code.
- 2Set environment variables: ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL.
- 3Run claude in your terminal at the project root.
export ANTHROPIC_AUTH_TOKEN="genfity_xxxxxxxxxxxx"
export ANTHROPIC_BASE_URL="https://ai.genfity.com"
export ANTHROPIC_MODEL="genfity/claude-opus-4.7"
export ANTHROPIC_SMALL_FAST_MODEL="genfity/claude-haiku-4.5"
export API_TIMEOUT_MS="300000"
claudeopencode
AI coding agent in your terminal (SST)
opencode is an open-source TUI-based coding agent. Add Genfity as an OpenAI-compatible provider.
- 1Install: curl -fsSL https://opencode.ai/install | bash.
- 2Create ~/.config/opencode/opencode.json (global) or opencode.json at project root.
- 3Set API key: export GENFITY_KEY="genfity_xxxxxxxxxxxx".
- 4Run opencode in your terminal and select the Genfity provider.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"genfity": {
"npm": "@ai-sdk/openai-compatible",
"name": "Genfity",
"options": {
"baseURL": "https://ai.genfity.com/v1",
"apiKey": "{env:GENFITY_KEY}"
},
"models": {
"genfity/claude-opus-4.7": { "name": "Claude Opus 4.7" }
}
}
}
}Codex CLI
OpenAI Codex CLI agent
Codex CLI supports OpenAI-compatible providers via ~/.codex/config.toml. Add Genfity as a custom provider.
- 1Install: npm i -g @openai/codex.
- 2Edit ~/.codex/config.toml — add the [model_providers.genfity] block.
- 3Set API key: export GENFITY_KEY="genfity_xxxxxxxxxxxx".
- 4Run: codex --provider genfity --model genfity/claude-opus-4.7.
model_provider = "genfity"
model = "genfity/claude-opus-4.7"
[model_providers.genfity]
name = "Genfity"
base_url = "https://ai.genfity.com/v1"
env_key = "GENFITY_KEY"
wire_api = "chat"Aider
AI pair programming in your terminal
Aider reads OpenAI-style environment variables. Override OPENAI_API_BASE and OPENAI_API_KEY for Genfity.
- 1Install: pipx install aider-chat or pip install aider-chat.
- 2Export environment variables (shell profile or .env).
- 3Run from project root: aider --model openai/genfity/claude-opus-4.7.
export OPENAI_API_BASE="https://ai.genfity.com/v1"
export OPENAI_API_KEY="genfity_xxxxxxxxxxxx"
aider --model openai/genfity/claude-opus-4.7LLM (Simon Willison)
Versatile CLI + Python library for any LLM
LLM CLI uses the llm-openai-plugin for OpenAI-compatible providers. Register Genfity as a new model.
- 1Install: pipx install llm then llm install llm-openai-plugin.
- 2Save API key: llm keys set genfity (paste genfity_xxxxxxxxxxxx).
- 3Edit extra-openai-models.yaml in the llm config dir.
- 4Test: llm -m genfity/claude-opus 'hello'.
- model_id: genfity/claude-opus
model_name: genfity/claude-opus-4.7
api_base: "https://ai.genfity.com/v1"
api_key_name: genfity
can_stream: trueDesktop & Web UI
Genfity AI Gateway uses OpenAI-compatible and Anthropic-compatible formats, so almost any IDE, CLI, or SDK that supports custom base URLs works out of the box. Just change the base URL and use your Dashboard API key.
LibreChat
Self-hosted multi-model chat UI
LibreChat uses librechat.yaml to register custom endpoints. Add Genfity as a custom endpoint.
- 1Copy librechat.example.yaml → librechat.yaml (deploy root).
- 2Add the endpoints.custom block as shown.
- 3Set GENFITY_KEY in .env (mounted to the container).
- 4Restart the container: docker compose up -d.
version: 1.0.9
endpoints:
custom:
- name: "Genfity"
apiKey: "${GENFITY_KEY}"
baseURL: "https://ai.genfity.com/v1"
models:
default: ["genfity/claude-opus-4.7"]
fetch: true
titleModel: "genfity/claude-haiku-4.5"
summarize: false
forcePrompt: falseOpen WebUI
Extensible ChatGPT-style web UI
Open WebUI can add multiple OpenAI-compatible connections in Admin Settings.
- 1Sign in as admin → Admin Panel → Settings → Connections.
- 2OpenAI API → click + to add a new connection.
- 3Fill: API Base URL = https://ai.genfity.com/v1, API Key = genfity_xxxxxxxxxxxx.
- 4Save → Genfity models appear in the Workspace dropdown.
API Base URL = https://ai.genfity.com/v1
API Key = genfity_xxxxxxxxxxxx
Prefix ID = genfity (optional)Chatbox
Cross-platform desktop AI client
Chatbox supports a custom OpenAI host. Open Settings → AI Model → choose OpenAI API and fill the Genfity host + key.
- 1Download Chatbox (macOS/Windows/Linux) or use the web version.
- 2Settings → Model → AI Provider = OpenAI API.
- 3Fill API Key + API Host = https://ai.genfity.com/v1.
- 4Choose Model = genfity/claude-opus-4.7 → Save.
AI Provider = OpenAI API
API Key = genfity_xxxxxxxxxxxx
API Host = https://ai.genfity.com/v1
Model = genfity/claude-opus-4.7Jan
Offline-first personal AI
Jan supports remote providers via Settings → Model Providers → OpenAI.
- 1Settings → Model Providers → OpenAI.
- 2Fill API Key = genfity_xxxxxxxxxxxx, Base URL = https://ai.genfity.com/v1.
- 3Models tab → import a model with ID genfity/claude-opus-4.7.
- 4Start a new thread and pick the Genfity model.
Provider = OpenAI (compatible)
Base URL = https://ai.genfity.com/v1
API Key = genfity_xxxxxxxxxxxx
Model ID = genfity/claude-opus-4.7LM Studio
Desktop UI for local + remote LLMs
LM Studio supports remote OpenAI-compatible endpoints via the Connect to a server feature.
- 1LM Studio → Chat icon → click Select a model.
- 2Dropdown → Server settings → Add remote endpoint.
- 3Base URL = https://ai.genfity.com/v1, API Key = genfity_xxxxxxxxxxxx.
- 4Click Load → choose genfity/claude-opus-4.7.
Base URL = https://ai.genfity.com/v1
API Key = genfity_xxxxxxxxxxxx
Model = genfity/claude-opus-4.7SDK & Framework
Genfity AI Gateway uses OpenAI-compatible and Anthropic-compatible formats, so almost any IDE, CLI, or SDK that supports custom base URLs works out of the box. Just change the base URL and use your Dashboard API key.
OpenAI Python SDK
Official Python client
The OpenAI Python SDK accepts a base_url argument. Just change the base URL and API key.
- 1Install: pip install openai.
- 2Instantiate the client with the Genfity base URL.
- 3Call chat.completions.create(...) as usual.
from openai import OpenAI
client = OpenAI(
api_key="genfity_xxxxxxxxxxxx",
base_url="https://ai.genfity.com/v1",
)
res = client.chat.completions.create(
model="genfity/claude-opus-4.7",
messages=[{"role": "user", "content": "Hello Genfity"}],
)
print(res.choices[0].message.content)OpenAI Node SDK
Official TypeScript / Node client
The OpenAI Node SDK accepts a baseURL on instantiation. Fully compatible with Genfity chat completions.
- 1Install: npm i openai.
- 2Set GENFITY_KEY env var, then use as in the snippet.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GENFITY_KEY,
baseURL: "https://ai.genfity.com/v1",
});
const res = await client.chat.completions.create({
model: "genfity/claude-opus-4.7",
messages: [{ role: "user", content: "Hello Genfity" }],
});
console.log(res.choices[0].message.content);Anthropic Python SDK
Official Anthropic Python client
The Anthropic Python SDK accepts a base_url argument. Use the Genfity /v1/messages endpoint.
- 1Install: pip install anthropic.
- 2Instantiate the client with the Genfity base URL (without /v1).
- 3Call messages.create(...) as usual.
import anthropic
client = anthropic.Anthropic(
api_key="genfity_xxxxxxxxxxxx",
base_url="https://ai.genfity.com",
)
message = client.messages.create(
model="genfity/claude-opus-4.7",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello Genfity"}],
)
print(message.content[0].text)Anthropic Node SDK
Official Anthropic TypeScript client
The Anthropic Node SDK accepts a baseURL on instantiation. Use the Genfity /v1/messages endpoint.
- 1Install: npm i @anthropic-ai/sdk.
- 2Instantiate the client with the Genfity base URL (without /v1).
- 3Call messages.create(...) as usual.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.GENFITY_KEY,
baseURL: "https://ai.genfity.com",
});
const message = await client.messages.create({
model: "genfity/claude-opus-4.7",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello Genfity" }],
});
console.log(message.content[0].text);LangChain
LLM orchestration framework
Use ChatOpenAI with the Genfity base_url — pattern is identical to OpenAI direct.
- 1Install: pip install langchain-openai.
- 2Instantiate ChatOpenAI with base_url + api_key.
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="genfity/claude-opus-4.7",
api_key="genfity_xxxxxxxxxxxx",
base_url="https://ai.genfity.com/v1",
temperature=0.2,
)
print(llm.invoke("Hello Genfity").content)Vercel AI SDK
TypeScript toolkit for AI apps
Use @ai-sdk/openai with the createOpenAI({ baseURL }) helper.
- 1Install: npm i ai @ai-sdk/openai.
- 2Call createOpenAI with the Genfity baseURL.
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";
const genfity = createOpenAI({
apiKey: process.env.GENFITY_KEY!,
baseURL: "https://ai.genfity.com/v1",
});
const { text } = await generateText({
model: genfity("genfity/claude-opus-4.7"),
prompt: "Hello Genfity",
});
console.log(text);Laravel (PHP)
PHP HTTP client integration
Use Http::withToken to send requests to Genfity AI Gateway from Laravel.
- 1Set GENFITY_KEY in .env.
- 2Use Illuminate\Support\Facades\Http for POST requests.
- 3Parse the response with ->json().
use Illuminate\Support\Facades\Http;
$response = Http::withToken(env('GENFITY_KEY'))
->post('https://ai.genfity.com/v1/chat/completions', [
'model' => 'genfity/claude-opus-4.7',
'messages' => [
['role' => 'user', 'content' => 'Hello Genfity'],
],
]);
return $response->json();

