> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dgrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Gemini 原生格式
> Gemini-native generateContent interface for text chat, multimodal media recognition (images, audio, video), speech synthesis, and image generation with structured parts. Use `generationConfig` to request specific response modalities such as speech (`speechConfig`) or images (`imageConfig`).
本頁使用與 [生成內容（Gemini）](/zh-Hant/api-reference/chat/generate-content) 相同的 `generateContent` 操作，上方 playground 已預先填入純文字對話範例。以下說明可加入 `generationConfig` 的 Gemini 原生欄位，以便透過結構化 parts 請求音訊理解或音訊生成。
請將 `generationConfig.responseModalities` 設為 `["AUDIO"]` 以要求音訊輸出，並設定 `generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName` 來選擇生成語音時要使用的預建聲音。
### Gemini 原生請求欄位
| 欄位 | 類型 | 必填 | 說明 |
| ------------------------------------------------------------------------- | ------ | -- | ----------------------- |
| `generationConfig.responseModalities` | array | 是 | 要求的回應模態，例如 `["AUDIO"]`。 |
| `generationConfig.speechConfig` | object | 否 | 語音設定物件。 |
| `generationConfig.speechConfig.voiceConfig` | object | 否 | 聲音設定包裝物件。 |
| `generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig` | object | 否 | 預建聲音設定。 |
| `generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName` | string | 否 | 預建聲音名稱，例如 `Kore`。 |
當你需要音訊輸出時，請在 `model` 路徑參數中使用具備文字轉語音能力的模型，例如 `gemini-2.5-flash-preview-tts`。
### 範例：請求語音音訊
```json theme={null}
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Say cheerfully: Have a wonderful day!" }
]
}
],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
}
}
```
### 回應欄位
回應遵循標準 `generateContent` 結構。當要求音訊輸出時，回傳的 `parts` 會包含內嵌音訊資料而非文字：
模型回傳的候選回應。
生成內容物件。
生成內容區塊中回傳的角色，通常為 `model`。
回傳的 parts。若為音訊輸出，每個 part 都會包含 `inlineData` 物件，其中含有 `mimeType`（例如 `audio/L16;codec=pcm;rate=24000`）與 base64 編碼的 `data`。
完成原因字串，例如 `STOP`。
安全評估結果。
Token 計量資訊，包括 `promptTokenCount`、`candidatesTokenCount` 與 `totalTokenCount`。
在適用情況下的 prompt 阻擋回饋資訊。
### 回應範例
```json 200 theme={null}
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "audio/L16;codec=pcm;rate=24000",
"data": ""
}
}
]
},
"finishReason": "STOP",
"safetyRatings": []
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 0,
"totalTokenCount": 10
}
}
```
## OpenAPI
````yaml api-reference/openapi.json POST /v1/models/{model}:generateContent
openapi: 3.1.0
info:
title: DGrid AI Gateway API
description: >-
A single, unified API to access 200+ leading AI models. OpenAI-, Claude-,
and Gemini-compatible endpoints for chat, completions, embeddings, images,
audio, and moderations.
version: 1.0.0
contact:
name: DGrid AI
url: https://dgrid.ai
servers:
- url: https://api.dgrid.ai
description: DGrid AI Gateway
security:
- bearerAuth: []
paths:
/v1/models/{model}:generateContent:
post:
tags:
- Chat
summary: Generate content (Gemini)
description: >-
Gemini-native generateContent interface for text chat, multimodal media
recognition (images, audio, video), speech synthesis, and image
generation with structured parts. Use `generationConfig` to request
specific response modalities such as speech (`speechConfig`) or images
(`imageConfig`).
operationId: generateContent
parameters:
- name: model
in: path
required: true
schema:
type: string
description: Target model ID, such as `gemini-1.5-pro`.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
contents:
type: array
description: Input content array with role and parts.
items:
type: object
properties:
role:
type: string
description: Content role.
parts:
type: array
description: Content parts (text, inline data, media).
items:
type: object
generationConfig:
type: object
description: Generation configuration.
properties:
responseModalities:
type: array
items:
type: string
description: >-
Requested response modalities, such as `TEXT`, `AUDIO`,
or `IMAGE`.
speechConfig:
type: object
description: Speech configuration for audio output.
properties:
voiceConfig:
type: object
properties:
prebuiltVoiceConfig:
type: object
properties:
voiceName:
type: string
description: Voice preset name.
imageConfig:
type: object
description: Image configuration for image output.
properties:
aspectRatio:
type: string
description: Aspect ratio.
imageSize:
type: string
description: Image size.
example:
contents:
- role: user
parts:
- text: Hello from DGrid.
responses:
'200':
description: Generated content candidates.
content:
application/json:
schema:
type: object
properties:
candidates:
type: array
description: Candidate responses returned by the model.
items:
type: object
properties:
content:
type: object
description: Generated content object.
properties:
role:
type: string
description: Role in the generated content block.
parts:
type: array
description: Returned content parts.
items:
type: object
finishReason:
type: string
description: Finish reason string.
safetyRatings:
type: array
description: Safety evaluation results.
items:
type: object
usageMetadata:
type: object
description: Token accounting metadata.
properties:
promptTokenCount:
type: integer
candidatesTokenCount:
type: integer
totalTokenCount:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
components:
responses:
BadRequest:
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error:
type: object
properties:
message:
type: string
type:
type: string
param:
type: string
code:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Your DGrid API key. All endpoints use `Authorization: Bearer
`.
````