## DeepNLP OneKey LLM Router API Document **Important**: Set the unified gateway key in `.env` as `DEEPNLP_ONEKEY_ROUTER_ACCESS` and use `X-OneKey` for all requests. You do **not** need individual provider API keys (Gemini/Claude/OpenAI) on the client side. This router acts as a unified gateway and handles provider access for you. ## OneKey LLM Router REST API **Base URL** - https://agent.deepnlp.org/llm **Auth Header** - `X-OneKey: $DEEPNLP_ONEKEY_ROUTER_ACCESS` **Endpoint** - `POST /llm` **Request Body (Chat)** - `provider` (str): `gemini` | `claude` | `openai` (default: `gemini`) - `model` (str, optional): provider model override - `messages` (list): chat messages - `images` (list, optional): image references (URL, base64 string, or data URI) - `temperature` (float, optional): default `0.7` - `response_format` (str, optional): `text` | `json` - `**kwargds` (object, optional): provider-specific kwargs (see below) **Response** - Provider JSON response with `success: true/false` and payload from the upstream provider. --- ## Gemini ### 1. Chat Model API **Supported Models** | Model | Input/Output | | ---- | ---- | | gemini-3-flash-preview | Multi-Modal/Text | | gemini-3.1-flash-lite-preview | Multi-Modal/Text | | gemini-3.1-pro-preview | Multi-Modal/Text | Gemini chat endpoint supports multi-modal input (text + images) and optional thinking controls. - text prompt into the `message` field with user/system prompt, and - Image prompt: Set the Image URL or Base64 value to the `images` field And we will handle the router to Gemini API calling, the comparison is like: **Python Provider Method** - `GeminiProvider.chat(messages, images=None, **kwargs)` **Messages Format** ```json [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Describe this image."}, {"role": "user", "content": "", "inline_data": {"mime_type": "image/jpeg", "data": ""}} ] ``` **Images** - `images` is a list of references. Supported inputs: - Web URL: `https://...` - Base64 string (raw) - Data URI: `data:image/png;base64,...` - Raw bytes (when using the provider directly in Python) **Supported kwargs** - `model` (str): defaults to `GEMINI_MODEL` env var - `temperature` (float): default `0.7` - `response_format` (str): `json` or `text` - `json` maps to `response_mime_type: application/json` - otherwise `text/plain` - `thinking_budget` (int): sets `thinkingConfig.thinkingBudget` - `thinking_level` (str): sets `thinkingConfig.thinkingLevel` (`low`, `medium`, `high`) - `include_thoughts` (bool): sets `thinkingConfig.includeThoughts` **OneKey LLM Router Usage Example** ```bash export DEEPNLP_ONEKEY_ROUTER_ACCESS=your_onekey_router_access curl -X POST "https://agent.deepnlp.org/llm" \ -H "Content-Type: application/json" \ -H "X-OneKey: $DEEPNLP_ONEKEY_ROUTER_ACCESS" \ -d '{ "provider": "gemini", "model": "gemini-3.1-flash-lite-preview", "messages": [ {"role": "system", "content": "Act as a LEGO master builder. Output ONLY valid JSON. Similar to the logo in reference images"}, {"role": "user", "content": "Generate a LEGO blueprint for a vintage 1960s race car. Format: List of JSON as {\"color\": \"red\", \"shape\": [1, 6, 1], \"position\": [x,y,z]}."} ], "images": [ "https://avatars.githubusercontent.com/u/242328252?s=200&v=4" ], "temperature": 0.1, "response_format": "json", "thinking_budget": 0, "thinking_level": "low", "include_thoughts": false }' ``` **Original Gemini API Calling Example** See Documents at [Gemini API](https://ai.google.dev/gemini-api/docs) ```shell curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "contents": [ { "parts": [ { "text": "Explain how AI works in a few words" }, { "inline_data": {"mime_type":"image/png", "data": ""} }, ] } ] }' ``` ### 2. Image Generation **Supported Models** | Model | Input/Output | |--------------------------------| ------------ | | gemini-2.5-flash-image | Image Generation | | gemini-3.1-flash-image-preview | Image Generation | | gemini-3-pro-image-preview | Image Generation | Gemini image generation uses the `generateContent` API with image output modalities. **Python Provider Method** - `GeminiProvider.generate_image(messages, images=None, **kwargs)` **Supported kwargs** - `model` (str): default `gemini-3.1-flash-image-preview` - `n` (int): number of images; capped at `10` - `temperature` (float): default `1.0` - `aspect_ratio` (str): e.g. `1:1`, `16:9` - `image_size` (str): provider-specific size option (Gemini 3 image models) - `thinking_level` (str): `low` | `medium` | `high` - `include_thoughts` (bool) **Notes** - If `model` is `gemini-2.5-flash-image`, only the first 3 image inputs are used for stability. - Input images can be supplied via `images` or as `inline_data` in `messages`. --- ```bash export DEEPNLP_ONEKEY_ROUTER_ACCESS=your_onekey_router_access curl -X POST "https://agent.deepnlp.org/llm" \ -H "Content-Type: application/json" \ -H "X-OneKey: $DEEPNLP_ONEKEY_ROUTER_ACCESS" \ -d '{ "provider": "gemini", "model": "gemini-3.1-flash-lite-preview", "messages": [ {"role": "system", "content": "Act as a LEGO master builder. Output ONLY valid JSON."}, {"role": "user", "content": "Generate a LEGO blueprint for a vintage 1960s race car. Format: List of JSON as {\"color\": \"red\", \"shape\": [1, 6, 1], \"position\": [x,y,z]}."} ], "images": [ "https://avatars.githubusercontent.com/u/242328252?s=200&v=4" ], "temperature": 0.1, "response_format": "json", "thinking_budget": 0, "thinking_level": "low", "include_thoughts": false }' ``` ``` curl -s -X POST \ "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -d "{ \"contents\": [{ \"parts\":[ {\"text\": \"An office group photo of these people, they are making funny faces.\"}, {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"\"}}, {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"\"}}, {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"\"}}, {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"\"}}, {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"\"}} ] }], \"generationConfig\": { \"responseModalities\": [\"TEXT\", \"IMAGE\"], \"imageConfig\": { \"aspectRatio\": \"5:4\", \"imageSize\": \"2K\" } } }" ``` ## Claude Available Soon ### 1. Chat Model API Claude chat forwards messages directly to the Anthropic Messages API. **Python Provider Method** - `ClaudeProvider.chat(messages, images=None, **kwargs)` **Supported kwargs** - `model` (str): defaults to `ANTHROPIC_MODEL` env var **Fixed Behavior** - `max_tokens` is fixed at `2048` in the current implementation. - `images` is accepted in the signature but not used in the payload. **Router Usage (Chat)** ```bash curl -X POST "https://agent.deepnlp.org/llm" \ -H "Content-Type: application/json" \ -H "X-OneKey: $DEEPNLP_ONEKEY_ROUTER_ACCESS" \ -d '{ "provider": "claude", "model": "claude-3-5-sonnet-20240620", "messages": [ {"role": "user", "content": "Summarize the main points of the RFC."} ] }' ``` --- ## OpenAI Available Soon ### 1. Chat Model API OpenAI chat uses the Chat Completions API. **Python Provider Method** - `OpenAIProvider.chat(messages, images=None, **kwargs)` **Supported kwargs** - `model` (str): default `gpt-4o-mini` - `temperature` (float): default `0.7` **Router Usage (Chat)** ```bash curl -X POST "https://agent.deepnlp.org/llm" \ -H "Content-Type: application/json" \ -H "X-OneKey: $DEEPNLP_ONEKEY_ROUTER_ACCESS" \ -d '{ "provider": "openai", "model": "gpt-4o-mini", "messages": [ {"role": "user", "content": "Write a haiku about routers."} ], "temperature": 0.5 }' ```