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

[
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Describe this image."},
  {"role": "user", "content": "", "inline_data": {"mime_type": "image/jpeg", "data": "<base64>"}}
]

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

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

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": "<BASE64_DATA_IMG_1>"}
          },
        ]
      }
    ]
  }'

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.

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\": \"<BASE64_DATA_IMG_1>\"}},
            {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"<BASE64_DATA_IMG_2>\"}},
            {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"<BASE64_DATA_IMG_3>\"}},
            {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"<BASE64_DATA_IMG_4>\"}},
            {\"inline_data\": {\"mime_type\":\"image/png\", \"data\": \"<BASE64_DATA_IMG_5>\"}}
        ]
      }],
      \"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)

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)

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
  }'