# Gemini 4 Argon API

推荐使用 **Gemini 原生 GenerateContent 格式**，可完整表达思考参数、原生函数调用、签名状态与续写。已有 OpenAI 客户端也可使用 Chat Completions 兼容格式；兼容层的参数接受情况和行为可能不同，特别是 `reasoning_effort`，遇到兼容错误请改用原生 `generationConfig.thinkingConfig`。

## 地址与鉴权

将示例域名替换为本站域名。使用本站 API Key 与独立美元钱包。

| 格式 | POST 地址 | 鉴权 |
| --- | --- | --- |
| 原生 JSON（推荐） | `/api/v1beta/models/gemini-4-argon:generateContent` | `x-goog-api-key: 本站APIKey` 或 Bearer |
| 原生 SSE（推荐） | `/api/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse` | 同上 |
| OpenAI Chat Completions | `/api/v1/chat/completions` | `Authorization: Bearer 本站APIKey` |

原生接口通过路径选择模型和流式方式，正文不传 `model`、`messages` 或 `stream`。若同时提供 Bearer 与 `x-goog-api-key`，原生接口优先使用后者。请通过请求头发送密钥，不把密钥放在 URL 查询参数中。

`GET /api/v1/models` 与 `GET /api/v1/models/gemini-4-argon` 提供已开放模型及支持格式。每次请求独立执行并计费，没有后台轮询、自动重试、自动续写或幂等重放。SSE 在完整结果及计费核对后发送，无逐 Token 实时延迟保证；原生流在 EOF 结束，没有 `[DONE]`，OpenAI 流使用 `[DONE]`。单次请求最长四分钟，请求体最多 32 MiB。

## 原生调用

```bash
curl 'https://YOUR_SITE/api/v1beta/models/gemini-4-argon:generateContent' \
  -H 'x-goog-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "contents": [{"role":"user","parts":[{"text":"请检查这个方案并提出验证步骤。"}]}],
    "generationConfig": {
      "maxOutputTokens":4096,
      "thinkingConfig":{"thinkingLevel":"medium"}
    }
  }'
```

原生流只需把路径改为 `:streamGenerateContent?alt=sse`，curl 加 `--no-buffer`。

Python / Node.js 的 Google GenAI SDK 使用本站域名加 `/api` 为 `base_url` / `baseUrl`，`api_version` / `apiVersion` 为 `v1beta`，模型为 `gemini-4-argon`。不要在 base URL 中重复加 `/v1beta`。关闭 SDK 自动重试、自动续写和自动工具执行，避免重复消费。

## 原生请求参数

原生 JSON 参数及嵌套对象完整保留，包括新增扩展字段、JSON Schema 和函数参数。接口接收参数不代表模型支持或参数一定生效；不支持的组合会报错。本站鉴权、请求体限制、媒体规则和计费检查独立执行。

| 字段 | 说明 |
| --- | --- |
| `contents` | 必填，完整对话历史；`role` 为 `user` / `model`，`parts` 保留原顺序 |
| `systemInstruction` | 系统指令，如 `{"parts":[{"text":"简洁回答"}]}` |
| `tools`、`toolConfig` | 原生函数声明、函数调用设置及模型支持的内置工具 |
| `safetySettings` | 每个类别最多一项；未传时四项可配置过滤默认 `OFF`；显式设置按请求保留。模型内置保护仍可能拒绝内容 |
| `continuationToken` | 上次返回的不透明续写状态；保持原样，并重新提交原始 contents |
| `generationConfig` | 输出预算、思考、采样、结构化输出和各模态设置 |
| `labels` | 字符串键值元数据，需遵守模型对命名和长度的限制 |
| `serviceTier` | `unspecified`、`standard`、`flex`、`priority`，实际可用性由模型决定 |
| `store` | 请求记录控制，原样保留；不表示本站提供历史响应查询 |
| `cachedContent` | 原样保留，但此模型不支持显式缓存管理，不提供缓存资源创建接口 |

`generationConfig` 支持完整嵌套参数，包括：

- `maxOutputTokens`：含思考与正文；JSON 单次 1–32768，SSE 单次 1–65536。省略时使用相应接口默认上限。
- `thinkingConfig`：`thinkingLevel` 为 `low` / `medium` / `high`，默认 medium；`includeThoughts` 请求可用思考摘要。旧 `thinkingBudget` 与 level 不应混用。
- `stopSequences`：最多五项停止字符串。
- `responseMimeType`、`responseJsonSchema`、`responseFormat`：结构化输出，保留完整 schema。旧 `responseSchema` / `_responseJsonSchema` 仍可提交，但不应与新版 schema 混用。
- `responseModalities`、`candidateCount`：输出模态与候选数；此模型输出为文本。
- `temperature`、`topP`、`topK`、`seed`、`presencePenalty`、`frequencyPenalty`：采样参数可提交；部分新模型会忽略采样设置。
- `responseLogprobs`、`logprobs`、`mediaResolution`、`enableEnhancedCivicAnswers`、`enableAffectiveDialog`。
- `speechConfig`、`imageConfig`、`translationConfig`、`audioTranscriptionConfig` 等扩展嵌套对象。接收这些通用字段不代表此模型支持对应输出能力。

## 图片、音视频与 PDF

使用原生 `fileData` part，提供公开 HTTP(S) 地址及正确的 `mimeType`：

```json
{"role":"user","parts":[{"text":"总结这份资料"},{"fileData":{"fileUri":"https://YOUR_PUBLIC_HOST/document.pdf","mimeType":"application/pdf"}}]}
```

不支持 `inlineData`、base64 或 `data:` 媒体 URI；不能提交私有网络或需要额外鉴权的文件。文件是否受支持由模型决定。本站不提供 Google Files、Interactions、缓存管理或远程 Token 统计接口。

## 原生函数调用与续写

```json
{
  "contents":[{"role":"user","parts":[{"text":"杭州天气如何？"}]}],
  "tools":[{"functionDeclarations":[{
    "name":"weather",
    "description":"查询指定城市天气",
    "parametersJsonSchema":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}
  }]}],
  "toolConfig":{"functionCallingConfig":{"mode":"AUTO"}}
}
```

客户端执行 `functionCall` 后，把完整模型 `content` 原样放回历史，包括 `thoughtSignature`、函数 ID、part 顺序和所有原始 part；再追加 `user` 角色的 `functionResponse`。本站 API 不替客户端执行函数。

```json
{"role":"user","parts":[{"functionResponse":{"name":"weather","response":{"temperature":24}}}]}
```

若返回了函数 ID，结果中也应带上对应 ID。不要只用展示文本重建带签名的模型轮次。

`finishReason: CONTINUATION` 表示本次预算用尽，需要客户端决定是否继续；每次续写另行计费。保持 `continuationToken` 原样并提交原始输入。`MAX_TOKENS` 可在提高输出预算后继续。不要把任何部分正文视为完整成功；流内错误、结束状态及 EOF 均需处理。

## OpenAI 兼容调用

```bash
curl 'https://YOUR_SITE/api/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"model":"gemini-4-argon","messages":[{"role":"user","content":"你好"}],"max_tokens":1024,"stream":false}'
```

OpenAI SDK 的 `base_url` / `baseURL` 为本站域名加 `/api/v1`。支持提交 `model`、`messages`、`stream`、`stream_options`、`max_tokens` / `max_completion_tokens`、`temperature`、`top_p`、`stop`、`seed`、惩罚项、`tools`、`tool_choice`、`parallel_tool_calls`、`response_format`、`reasoning_effort` 及兼容接口接受的扩展参数，嵌套 schema 不裁剪。工具由客户端执行，完整历史由客户端提供。原生字段与 OpenAI 字段不要混成一份请求。流式结算会在内部收集 usage；显式设置 `stream_options: {"include_usage":false}` 时，对外省略用量事件，但仍按实际用量结算。

Gemini 4 Argon 在 `/api/v1/responses`、`/api/v1/messages` 与 `/api/v1/messages/count_tokens` 的旧接入已停用，返回 HTTP 410。请按上文示例迁移至 Chat Completions 或 Gemini 原生接口。

## 计费与异常处理

新接口按本站配置的输入、输出及缓存输入单价结算，单位美元 / 百万 Token。默认售价为输入 $1.60、缓存输入 $0.08、输出 $8.00；当前生效售价以模型详情的 billing 为准。输入包含普通 prompt 与工具使用输入；输出包含正文与思考 Token，思考不重复收费。缓存输入是输入子集，只按缓存单价计算一次。流式 usage 使用最终累计快照，不跨帧相加；最终金额向上取整到美元微单位。未配置售价或未开放的接口不能调用。

模型详情的 `billing.longContext` 存在时，单次总输入（含缓存输入）严格超过 `inputTokensAbove`，整次请求的输入、缓存读取和输出均按该档售价结算。

预冻结只用于余额准入，默认每个请求 2 美元；余额不足预冻结额但可用余额仍大于 0 时冻结全部剩余额度。成功按实际用量结算并释放剩余冻结，允许该次结算后余额为负；可用余额归零或欠费时拒绝新请求，充值先抵扣欠款。每个并行请求独立冻结。

超时、连接中断、无效用量或异常结果返回 `TEXT_RESULT_UNCERTAIN`，保留冻结待核对，请勿自动重试；明确拒绝解除冻结。旧兼容能力沿用其已开放的计费规则。错误、响应头与返回元数据不会包含内部接入信息或原始账单。