Gemini 原生接口

概述

AIone 支持以 Google Gemini 原生 API 格式直接调用网关，适用于自建网关聚合、Google Gemini SDK 以及已有 Gemini 对接代码的场景。

请求和响应格式与 Google Gemini API 完全一致，网关仅做认证、路由和计费，不做任何格式转换。

接入信息

注意： 传入的始终是 AIone 的 API Key（sk-nex-xxx），不是 Google 的 API Key。

认证方式

为兼容各类客户端，网关接受四种携带 API Key 的方式，任选其一即可（都传 sk-nex- 开头的 AIone Key）：

建议优先用请求头（Authorization / x-goog-api-key）。查询参数 ?key= 可能被访问日志或代理缓存记录，安全性较低；若客户端同时提供了请求头，网关以请求头为准。

这意味着可以直接把 Google 官方 google-genai SDK 指向本网关，无需改动鉴权代码——SDK 默认发送的 x-goog-api-key 头会被正确识别（把其中的值换成你的 sk-nex- Key 即可）。

支持的模型

所有已接入的 Gemini 模型均可通过原生接口调用，包括：

文本 / 多模态模型： gemini-2.5-flash、gemini-2.5-pro、gemini-3-pro-preview、gemini-3-flash-preview、gemini-3.1-pro-preview 等（-pro 系列支持图片 / 视频 / 音频理解，见 多模态理解）

图片生成模型： gemini-3.1-flash-image-preview、gemini-3-pro-image-preview、gemini-2.5-flash-image 等

完整列表请查询 GET https://api.portal.aiin1.ai/v1/models。

非流式请求 — generateContent

基础示例

curl https://api.portal.aiin1.ai/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "用一句话解释量子计算"}]}
    ],
    "generationConfig": {
      "maxOutputTokens": 256,
      "temperature": 0.7
    }
  }'

响应格式

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "量子计算是利用量子力学原理..."}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 25,
    "totalTokenCount": 35
  },
  "modelVersion": "gemini-2.5-flash"
}

图片生成示例

curl https://api.portal.aiin1.ai/v1beta/models/gemini-3.1-flash-image-preview:generateContent \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "画一只可爱的猫咪"}]}
    ],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "maxOutputTokens": 4096,
      "imageConfig": {
        "imageSize": "2K",
        "aspectRatio": "16:9"
      }
    }
  }'

图片在响应的 candidates[0].content.parts[] 中以 inlineData 形式返回（base64 编码）。

注意： 4K 图片生成可能需要 2-3 分钟，请将客户端 HTTP 超时设置为 ≥ 600 秒。

多模态理解（图片 / 视频 / 音频输入）

除文本外，contents[].parts[] 里还可以传入图片、视频、音频让模型理解（gemini-2.5-pro、gemini-3.1-pro-preview 等多模态文本模型支持）。素材有两种传法：

支持的视频格式：video/mp4、video/webm、video/mov、video/avi、video/mpeg、video/3gpp 等。

示例 A：内联 base64 视频（小文件）

curl https://api.portal.aiin1.ai/v1beta/models/gemini-3.1-pro-preview:generateContent \
  -H "x-goog-api-key: sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "这段视频里依次出现了哪些颜色？按顺序用逗号分隔列出。"},
        {"inline_data": {"mime_type": "video/mp4", "data": "<视频文件的 base64 编码>"}}
      ]
    }]
  }'

示例 B：公网 URL 视频（大文件）

curl https://api.portal.aiin1.ai/v1beta/models/gemini-3.1-pro-preview:generateContent \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "这段视频的主角是什么动物？用一句话回答。"},
        {"file_data": {"mime_type": "video/mp4", "file_uri": "https://example.com/sample-video.mp4"}}
      ]
    }]
  }'

图片理解同理：把 mime_type 换成 image/jpeg / image/png 即可（inline_data 内联或 file_data 传 URL）。

超时：视频理解耗时取决于视频长度和模型，长视频可能需要数十秒到数分钟；用公网 URL 时还叠加上游抓取该 URL 的耗时。建议 HTTP 超时设为 ≥ 300 秒。

暂不支持 Google File API 上传（/upload/v1beta/files 及 files/{id} 引用）。

⚠️ 超过 ~15 MB 的素材请用 大文件上传：公网 https:// URL 的 file_data 只会被上游读取前 ~15 MB，超出部分被静默丢弃（不会报错，但模型只"看到"了开头一段）。要让模型完整理解整个大文件,先用 大文件上传 接口拿到 gs:// 引用,再把它作为 file_data.file_uri 使用。

流式请求 — streamGenerateContent

在端点 URL 末尾加 ?alt=sse，响应以 SSE (Server-Sent Events) 格式逐 chunk 返回。

示例

curl https://api.portal.aiin1.ai/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse \
  -H "Authorization: Bearer sk-nex-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "写一首关于春天的诗"}]}
    ],
    "generationConfig": {
      "maxOutputTokens": 512
    }
  }'

SSE 响应格式

data: {"candidates":[{"content":{"parts":[{"text":"春风"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":2,"totalTokenCount":10}}

data: {"candidates":[{"content":{"parts":[{"text":"拂面来，"}],"role":"model"},"index":0}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":5,"totalTokenCount":13}}

data: {"candidates":[{"content":{"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":28,"totalTokenCount":36}}

每个 data: 行是一个独立的 JSON 对象。usageMetadata 是累积值，最后一个 chunk 的数值为最终用量。

注意： 图片生成模型不支持 streamGenerateContent，请使用 generateContent。

Python SDK 示例

import google.generativeai as genai
 
genai.configure(
    api_key="sk-nex-your-key-here",
    transport="rest",
    client_options={"api_endpoint": "https://api.portal.aiin1.ai"},
)
 
model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content("用一句话解释量子计算")
print(response.text)

Node.js SDK 示例

import { GoogleGenerativeAI } from "@google/generative-ai";
 
const genAI = new GoogleGenerativeAI("sk-nex-your-key-here");
// 需要设置自定义 endpoint
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });
 
const result = await model.generateContent("用一句话解释量子计算");
console.log(result.response.text());

注意： Google 官方 SDK 可能不直接支持自定义 endpoint。如果遇到此限制，建议使用 HTTP 直接调用或使用支持自定义 Base URL 的第三方库。

与 OpenAI 兼容格式的对比

两种格式访问的是同一组模型和同一组上游通道，选择哪种取决于你的客户端。

限制与注意事项

1. 认证方式：使用 AIone 的 sk-nex- API Key，不是 Google API Key；支持 Authorization / x-goog-api-key / x-api-key 头及 ?key= 查询参数四种携带方式（见 认证方式）
2. 图片模型不支持流式：streamGenerateContent 对图片生成模型会返回 503，请使用 generateContent
3. 支持的 action：仅支持 generateContent 和 streamGenerateContent，不支持 countTokens、embedContent 等
4. 超时设置：图片生成（尤其 4K）请将 HTTP 超时设置为 ≥ 600 秒；视频理解建议 ≥ 300 秒
5. 多模态输入上限：内联 inline_data 受整个请求体 20 MB 限制（原始文件 ≈ 15 MB）；更大的文件用 file_data 传公网 URL。不支持 Google File API 上传（/upload/v1beta/files）
6. 格式透传：请求和响应均为字节级透传，网关不做任何格式转换