generateContent

与 Gemini API 的 generateContent 接口兼容，可以直接使用 Google Gen AI SDK。

POST https://noviahub.com/v1beta/models/{model}:generateContent
POST https://noviahub.com/v1beta/models/{model}:streamGenerateContent?alt=sse

{model} 换成模型 ID，例如 gemini-3-flash。适用于端点标签里有 Gemini 的模型（在模型&价格页面查看）。

鉴权

以下写法任选一种：

写法	示例
请求头 x-goog-api-key	x-goog-api-key: <你的 API 密钥>
查询参数 key	...:generateContent?key=<你的 API 密钥>
请求头 Authorization	Authorization: Bearer <你的 API 密钥>

请求头还需要 Content-Type: application/json。

请求参数

请求体按 Gemini 规范书写。下表列出 NoviaHub 能识别并转发的字段，参数最终是否生效取决于模型本身。

参数	类型	必填	说明
contents	array	是	对话内容。每项包含 role（user 或 model）和 parts。
systemInstruction	object	否	系统指令，结构与 contents 中的一项相同。也接受下划线写法 system_instruction。
generationConfig	object	否	生成设置，字段见下表。
tools	array	否	可用工具（函数声明、搜索等），原样转发。
toolConfig	object	否	工具调用设置。
safetySettings	array	否	安全设置。
cachedContent	string	否	使用已创建的上下文缓存。

parts 中每一项可以是 text（文字）、inlineData（mimeType + Base64 编码的 data，用于图片等文件）、fileData、functionCall、functionResponse 等。

generationConfig 中可用的字段：temperature、topP、topK、maxOutputTokens、candidateCount、stopSequences、responseMimeType、responseSchema、responseJsonSchema、presencePenalty、frequencyPenalty、seed、responseLogprobs、logprobs、responseModalities、mediaResolution、thinkingConfig（includeThoughts、thinkingBudget、thinkingLevel）、speechConfig、imageConfig。这些字段也接受下划线写法（如 max_output_tokens）。

注意

不在上述清单里的字段会被丢弃。

示例代码

cURL

curl "https://noviahub.com/v1beta/models/gemini-3-flash:generateContent" \
  -H "x-goog-api-key: $NOVIAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "用一句话解释什么是 API。"}]}]
  }'

Python

import os

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NOVIAHUB_API_KEY"],
    http_options=types.HttpOptions(base_url="https://noviahub.com"),
)

response = client.models.generate_content(
    model="gemini-3-flash",
    contents="用一句话解释什么是 API。",
)

print(response.text)

TypeScript

import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: process.env.NOVIAHUB_API_KEY,
  httpOptions: { baseUrl: 'https://noviahub.com' },
})

const response = await ai.models.generateContent({
  model: 'gemini-3-flash',
  contents: '用一句话解释什么是 API。',
})

console.log(response.text)

Google Gen AI SDK 的 base_url 只填 https://noviahub.com，不要带 /v1beta。

响应

字段	说明
candidates[].content.parts[]	回复内容。文字在 text 字段；图片模型生成的图片在 inlineData（mimeType 和 Base64 编码的 data）。
candidates[].finishReason	停止原因，如 STOP（正常结束）、MAX_TOKENS（达到长度上限）。
usageMetadata.promptTokenCount	输入 token 数。
usageMetadata.candidatesTokenCount	输出 token 数。
usageMetadata.totalTokenCount	合计。
usageMetadata.thoughtsTokenCount	思考部分的 token 数（模型提供时）。
usageMetadata.cachedContentTokenCount	命中缓存的 token 数（模型提供时）。
modelVersion	模型版本。
responseId	本次回复的 ID。

示例响应（本地测试环境，内容由模拟上游生成）

{
  "candidates": [
    {
      "content": { "role": "model", "parts": [{ "text": "Hello from the mock upstream." }] },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": { "promptTokenCount": 12, "candidatesTokenCount": 7, "totalTokenCount": 19 },
  "modelVersion": "gemini-3-flash",
  "responseId": "mock-resp-123"
}

用本接口调用非 Gemini 模型时（经过协议转换），响应里会多出 safetyRatings（空数组）以及 usageMetadata 里的一些网关内部字段，可以忽略。

流式输出

使用 streamGenerateContent，并在地址后面加上 ?alt=sse。响应以 SSE 返回，每段 data: 是一个与上面结构相同的对象，文字分段出现在 candidates[0].content.parts[0].text 里；最后一段带 finishReason 和完整的 usageMetadata。

实测中，即使不加 ?alt=sse，NoviaHub 也按 SSE 返回。为了和各种客户端保持一致，建议始终加上。

示例流式响应（本地测试环境）

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Hello"}]},"index":0}],"usageMetadata":{"promptTokenCount":12,"totalTokenCount":12},"modelVersion":"gemini-3-flash","responseId":"mock-resp-123"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" from the mock upstream."}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":12,"candidatesTokenCount":7,"totalTokenCount":19},"modelVersion":"gemini-3-flash","responseId":"mock-resp-123"}

cURL

curl "https://noviahub.com/v1beta/models/gemini-3-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $NOVIAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{"contents": [{"parts": [{"text": "写一首四句的短诗。"}]}]}'

Python

import os

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NOVIAHUB_API_KEY"],
    http_options=types.HttpOptions(base_url="https://noviahub.com"),
)

for chunk in client.models.generate_content_stream(
    model="gemini-3-flash",
    contents="写一首四句的短诗。",
):
    print(chunk.text or "", end="", flush=True)

TypeScript

import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: process.env.NOVIAHUB_API_KEY,
  httpOptions: { baseUrl: 'https://noviahub.com' },
})

const stream = await ai.models.generateContentStream({
  model: 'gemini-3-flash',
  contents: '写一首四句的短诗。',
})

for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? '')
}

生成图片

Gemini 图片模型（如 gemini-3.1-flash-image）用的也是本接口。把 {model} 换成图片模型的 ID，生成的图片在响应的 inlineData 里，把 data 按 Base64 解码后保存为 mimeType 对应格式的文件即可。这类模型不能用 /v1/images/generations 调用，详见图片生成。

不支持的功能

• :countTokens（计算 token 数）不可用，调用会返回 404。

常见错误

HTTP 状态码	原因
400	请求体不是合法 JSON。
401	密钥无效、已禁用、已过期或额度已用完，或密钥放错了位置。
403	密钥不允许使用这个模型、IP 不在白名单，或账户余额不足。
503	模型 ID 写错，或该模型当前没有可用线路。

错误响应使用 OpenAI 结构（{"error": {...}}），见 API 概览 · 错误格式。完整说明见错误码与排查。