Zivv Docs

主题

Gemini 原生协议使用 ​

Zivv 兼容 Gemini 原生 API，你可以直接用 Google 官方 google-genai SDK，或用 curl 调用原生端点，只需把 Base URL 指向 Zivv、认证换成你的 Zivv Key。

端点与认证 ​

项目值
Base URLhttps://zivv.pro
生成POST /v1beta/models/{model}:generateContent
流式生成POST /v1beta/models/{model}:streamGenerateContent
认证请求头 x-goog-api-key: sk-你的Key

curl ​

generateContent（非流式） ​

bash
curl 'https://zivv.pro/v1beta/models/YOUR_MODEL_ID:generateContent' \
  -H 'x-goog-api-key: sk-你的Key' \
  -H 'Content-Type: application/json' \
  -d '{
  "contents": [
    { "parts": [{"text": "Hello!"}] }
  ]
}'

响应示例：

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{"text": "Hello! How can I help you?"}]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 3,
    "candidatesTokenCount": 8
  }
}

streamGenerateContent（流式） ​

bash
curl 'https://zivv.pro/v1beta/models/YOUR_MODEL_ID:streamGenerateContent?alt=sse' \
  -H 'x-goog-api-key: sk-你的Key' \
  -H 'Content-Type: application/json' \
  -d '{
  "contents": [
    { "parts": [{"text": "用 Python 写一个快速排序"}] }
  ]
}'

请求格式与 generateContent 相同，响应以 SSE 流返回。

Python（google-genai SDK） ​

安装 ​

bash
pip install google-genai

基本用法 ​

python
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的Key",
    http_options=types.HttpOptions(base_url="https://zivv.pro"),
)

response = client.models.generate_content(
    model="YOUR_MODEL_ID",
    contents="Hello!",
)

print(response.text)

流式输出 ​

python
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的Key",
    http_options=types.HttpOptions(base_url="https://zivv.pro"),
)

for chunk in client.models.generate_content_stream(
    model="YOUR_MODEL_ID",
    contents="用 Python 写一个快速排序",
):
    print(chunk.text, end="")

Node.js / TypeScript（@google/genai SDK） ​

安装 ​

bash
npm install @google/genai

基本用法 ​

typescript
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: 'sk-你的Key',
  httpOptions: { baseUrl: 'https://zivv.pro' },
})

const response = await ai.models.generateContent({
  model: 'YOUR_MODEL_ID',
  contents: 'Hello!',
})

console.log(response.text)

流式输出 ​

typescript
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: 'sk-你的Key',
  httpOptions: { baseUrl: 'https://zivv.pro' },
})

const stream = await ai.models.generateContentStream({
  model: 'YOUR_MODEL_ID',
  contents: '用 TypeScript 写一个快速排序',
})

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

生图（图像生成） ​

Gemini 原生协议通过同一个 generateContent 端点生图：使用模型广场中当前可用的图片模型（示例占位符为 YOUR_IMAGE_MODEL_ID），并在 generationConfig.responseModalities 中声明 Image。图片以 inlineData（Base64）返回在响应的 parts 中。

请求参数 ​

参数类型必填说明
contentsarray是内容数组；文生图只传 text，图生图额外传 inlineData（输入图片）
contents[].parts[].textstring是图片描述 / 编辑指令
contents[].parts[].inlineData.mimeTypestring否输入图片格式，如 image/png、image/jpeg
contents[].parts[].inlineData.datastring否输入图片的 Base64 数据（图生图时必填）
generationConfig.responseModalitiesarray是输出模态，生图须包含 "Image"，通常为 ["Text", "Image"]
generationConfig.imageConfig.aspectRatiostring否宽高比：1:1、16:9、9:16、4:3、3:4 等
generationConfig.imageConfig.imageSizestring否分辨率：1K（默认）、2K、4K
generationConfig.candidateCountinteger否生成数量，默认 1
generationConfig.temperaturenumber否采样温度
generationConfig.seedinteger否随机种子，固定可复现结果

完整参数请求示例：

json
{
  "contents": [
    { "parts": [{"text": "画一只戴墨镜的柯基，赛博朋克风格，霓虹灯背景"}] }
  ],
  "generationConfig": {
    "responseModalities": ["Text", "Image"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    },
    "candidateCount": 1,
    "temperature": 1.0,
    "seed": 12345
  }
}

curl（文生图） ​

bash
curl 'https://zivv.pro/v1beta/models/YOUR_IMAGE_MODEL_ID:generateContent' \
  -H 'x-goog-api-key: sk-你的Key' \
  -H 'Content-Type: application/json' \
  -d '{
  "contents": [
    { "parts": [{"text": "画一只卡通猫咪"}] }
  ],
  "generationConfig": { "responseModalities": ["Text", "Image"] }
}'

响应示例：

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgo...(base64 图片数据)..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

curl（图生图 / 编辑） ​

在 parts 中同时传入文本和输入图片（inlineData）即可编辑：

bash
curl 'https://zivv.pro/v1beta/models/YOUR_IMAGE_MODEL_ID:generateContent' \
  -H 'x-goog-api-key: sk-你的Key' \
  -H 'Content-Type: application/json' \
  -d '{
  "contents": [
    {
      "parts": [
        {"text": "把这张图改成夜晚场景"},
        {"inlineData": {"mimeType": "image/png", "data": "<输入图片的 base64>"}}
      ]
    }
  ],
  "generationConfig": { "responseModalities": ["Text", "Image"] }
}'

Python（google-genai SDK） ​

python
from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-你的Key",
    http_options=types.HttpOptions(base_url="https://zivv.pro"),
)

response = client.models.generate_content(
    model="YOUR_IMAGE_MODEL_ID",
    contents="画一只戴墨镜的柯基，赛博朋克风格，霓虹灯背景",
    config=types.GenerateContentConfig(
        response_modalities=["Text", "Image"],
        image_config=types.ImageConfig(aspect_ratio="16:9", image_size="2K"),
        candidate_count=1,
        temperature=1.0,
        seed=12345,
    ),
)

for part in response.candidates[0].content.parts:
    if part.text:
        print(part.text)
    elif part.inline_data:
        with open("output.png", "wb") as f:
            f.write(part.inline_data.data)

Node.js / TypeScript（@google/genai SDK） ​

typescript
import { GoogleGenAI } from '@google/genai'
import { writeFileSync } from 'node:fs'

const ai = new GoogleGenAI({
  apiKey: 'sk-你的Key',
  httpOptions: { baseUrl: 'https://zivv.pro' },
})

const response = await ai.models.generateContent({
  model: 'YOUR_IMAGE_MODEL_ID',
  contents: '画一只戴墨镜的柯基，赛博朋克风格，霓虹灯背景',
  config: {
    responseModalities: ['Text', 'Image'],
    imageConfig: { aspectRatio: '16:9', imageSize: '2K' },
    candidateCount: 1,
    temperature: 1.0,
    seed: 12345,
  },
})

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    writeFileSync('output.png', Buffer.from(part.inlineData.data, 'base64'))
  }
}

注意事项 ​

  • 认证使用请求头 x-goog-api-key，值为你的 Zivv Key（sk-xxx）
  • Base URL 为 https://zivv.pro，不带 /v1beta 后缀（SDK 会自动拼接）
  • 流式端点为 :streamGenerateContent，curl 直连建议加 ?alt=sse 以 SSE 格式返回
  • 生图需使用模型广场中当前可用的图片模型（示例占位符为 YOUR_IMAGE_MODEL_ID）并在 responseModalities 中声明 Image，图片以 inlineData（Base64）返回
  • 分辨率用 imageConfig.imageSize 控制（1K/2K/4K），宽高比用 imageConfig.aspectRatio 控制
  • 请使用 模型广场 中列出的精确模型 ID
  • 端点完整定义见 API 端点

Zivv — OpenAI / Anthropic / Gemini 多协议 AI Gateway

© 2026 Zivv