home / skills / project-n-e-k-o / n.e.k.o / gemini-openai-api

gemini-openai-api skill

safe

This skill helps you integrate Gemini OpenAI compatible API, configure thinking, and normalize responses for seamless AI-assisted workflows.

npx playbooks add skill project-n-e-k-o/n.e.k.o --skill gemini-openai-api

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: gemini-openai-api
description: "Gemini 模型通过 OpenAI 兼容 API 接入指南。包含：(1) 辅助 API 配置（summary/correction/emotion/vision），(2) extra_body 格式用于控制 thinking，(3) 响应格式处理（markdown 代码块）。当需要将 Gemini 作为辅助模型接入、配置 thinking 参数、或处理 Gemini API 返回格式时使用。"
---

# Gemini OpenAI 兼容 API 接入

Gemini 提供 OpenAI 兼容端点，可作为辅助 API 使用。

## Base URL

```
https://generativelanguage.googleapis.com/v1beta/openai/
```

## 模型配置

| 用途                          | 推荐模型                   |
|-------------------------------|---------------------------|
| Summary / Correction / Vision | `gemini-3-flash-preview`  |
| Emotion Analysis              | `gemini-2.5-flash`        |

## 控制 Thinking

Gemini 2.5+ 模型需要通过 `extra_body` 控制 thinking 行为。

### 禁用 Thinking（用于 gemini-2.5-flash）

```python
extra_body = {
    "extra_body": {
        "google": {
            "thinking_config": {
                "thinking_budget": 0
            }
        }
    }
}
```

### 低级别 Thinking（用于 gemini-3-flash-preview）

```python
extra_body = {
    "extra_body": {
        "google": {
            "thinking_config": {
                "thinking_level": "low",
                "include_thoughts": False
            }
        }
    }
}
```

> [!IMPORTANT]
> extra_body 需要双层嵌套：外层 `"extra_body"` 是传给 OpenAI client 的参数名，内层 `{"google": {...}}` 是 Gemini 的实际配置。

## 响应格式处理

Gemini 可能返回 markdown 代码块包装的 JSON：

```
```json
{"emotion": "happy", "confidence": 0.8}
```
```

处理方法：

```python
if result_text.startswith("```"):
    lines = result_text.split("\n")
    if lines[0].startswith("```"):
        lines = lines[1:]
    if lines and lines[-1].strip() == "```":
        lines = lines[:-1]
    result_text = "\n".join(lines).strip()
```

## 配置文件位置

- `config/api_providers.json` - 添加 gemini 到 `assist_api_providers`
- `config/__init__.py` - 添加 `EXTRA_BODY_GEMINI` 和 `MODELS_EXTRA_BODY_MAP`

### api_providers.json 示例

```json
"gemini": {
  "key": "gemini",
  "name": "Gemini（Google）",
  "description": "Google AI 辅助模型，国内无法使用",
  "openrouter_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
  "summary_model": "gemini-3-flash-preview",
  "correction_model": "gemini-3-flash-preview",
  "emotion_model": "gemini-2.5-flash",
  "vision_model": "gemini-3-flash-preview"
}
```

## 常见问题

### "Unknown name 'google': Cannot find field"

原因：extra_body 格式错误，缺少外层 `"extra_body"` 包装。

解决：使用双层嵌套格式 `{"extra_body": {"google": {...}}}`。

### JSON 解析失败

原因：
1. 响应被截断（token 限制太小）
2. 响应包含 markdown 代码块

解决：
1. 增加 `max_completion_tokens`
2. 添加 markdown 代码块处理逻辑

Overview

This skill documents how to integrate Gemini models through an OpenAI-compatible API for use as an auxiliary model. It covers recommended models for common tasks, how to control Gemini 'thinking' with extra_body, and how to normalize Gemini responses that may be wrapped in Markdown code blocks. The guidance is focused on practical configuration and parsing steps for JavaScript or Python OpenAI-compatible clients.

How this skill works

The skill explains the OpenAI-compatible base URL and maps task types to Gemini models (summary/correction/vision vs. emotion). It shows how to pass Gemini-specific runtime controls by nesting a google object inside an outer extra_body parameter, and how to detect and strip Markdown code fences around JSON responses. It also points to where to add provider and extra_body mappings in application config files.

When to use it

When you need to add Gemini as a secondary/assist model behind an OpenAI-compatible client.
When you must control or disable the model's internal 'thinking' behaviors (Gemini 2.5+).
When Gemini responses include JSON wrapped in Markdown code blocks and need parsing.
When configuring provider entries and model mappings in application config files.
When selecting a task-appropriate Gemini model (summary, emotion, vision).

Best practices

Use the base URL https://generativelanguage.googleapis.com/v1beta/openai/ for OpenAI-compatible requests.
Always wrap Gemini runtime settings as {"extra_body": {"google": {...}}} — the outer key is required by the client.
Choose gemini-3-flash-preview for summary/correction/vision and gemini-2.5-flash for emotion analysis.
Disable or lower 'thinking' for predictable, deterministic outputs (set thinking_budget=0 or thinking_level='low').
Handle Markdown code fences before JSON parse: strip leading/trailing ``` blocks and then JSON.parse.

Example use cases

Adding Gemini to a multi-provider assistant where Gemini handles summarization and vision tasks.
Setting thinking_budget=0 for swift short responses from gemini-2.5-flash in realtime UIs.
Lowering include_thoughts and thinking_level for gemini-3-flash-preview to avoid internal chains of thought.
Preprocessing model output to remove ```json code fences before converting to structured data.
Registering gemini in config/api_providers.json and mapping EXTRA_BODY_GEMINI in config/__init__.py.

FAQ

Why do I get "Unknown name 'google': Cannot find field"?

That error means extra_body was formatted incorrectly. Use the required double-nested shape: {"extra_body": {"google": {...}}} so the client forwards the google object correctly.

JSON.parse fails on the model response. What should I check?

First ensure max_completion_tokens is large enough to avoid truncation. Second, strip any Markdown code fences (```...```) that may wrap the JSON before parsing.