TokenLab

Gemini gốc

Tạo nội dung (Generate Content)

Tạo nội dung bằng định dạng Google Gemini API

POST
/v1beta/models/{model}:generateContent

Sử dụng các định dạng yêu cầu và phản hồi của Gemini với một model được trả về bởi Liệt kê các Model. Các tên trường theo định dạng ProtoJSON lowerCamelCase và định dạng proto snake_case tương ứng đều được chấp nhận. Các trường và giá trị tùy chọn được hỗ trợ phụ thuộc vào model đã chọn.

Tham số đường dẫn (Path Parameters)

modelstringpathbắt buộc

Tên model (ví dụ: gemini-2.5-pro, gemini-3.5-flash).

Tham số truy vấn (Query Parameters)

keystringquery

API key (thay thế cho xác thực qua header).

Xác thực (Authentication)

Các endpoint của Gemini hỗ trợ nhiều phương thức xác thực:

  • Tham số truy vấn ?key=YOUR_API_KEY
  • Header x-goog-api-key: YOUR_API_KEY
  • Header Authorization: Bearer YOUR_API_KEY

Nội dung yêu cầu (Request Body)

contentsarraybắt buộc

Nội dung hội thoại với parts và một role tùy chọn. Các phần phương tiện (media parts) sử dụng inlineData / inline_data hoặc fileData / file_data. Các tệp và Cache ID do TokenLab tạo ra chỉ có thể được sử dụng trong Workspace sở hữu chúng.

systemInstructionobject

Hướng dẫn hệ thống (system instruction) cho model.

generationConfigobject

Các cài đặt tạo nội dung như temperature, topP, topK, maxOutputTokens, stopSequences, candidateCount, responseModalities, responseMimeType, responseSchema, và thinkingConfig. Các tên theo định dạng snake_case tương ứng cũng được chấp nhận. Các giá trị và tổ hợp được hỗ trợ phụ thuộc vào model.

safetySettingsarray

Các cài đặt bộ lọc an toàn.

toolsarray

Các công cụ Gemini như functionDeclarations. Các loại công cụ được hỗ trợ phụ thuộc vào model.

toolConfigobject

Cấu hình công cụ như functionCallingConfig.

cachedContentstring

Tên của nội dung được lưu trong bộ nhớ đệm (cached content) được tạo bằng Tạo nội dung cache, ví dụ cachedContents/abc123. Nó chỉ hoạt động trong Workspace đã tạo ra nó.

Mọi trường lowerCamelCase hiển thị ở trên cũng có thể sử dụng cách viết snake_case proto chính thức của nó, ví dụ system_instruction, generation_config, safety_settings, tool_config, cached_content, file_data.file_uri, và inline_data.mime_type.

Các phương thức được hỗ trợ

API tương thích với Gemini bao gồm Liệt kê các Model, Lấy thông tin Model, generateContent, streamGenerateContent, countTokens, Files, và nội dung cache. Các tính năng Gemini Interactions và Live hiện không khả dụng.

Hãy đọc phản hồi Lấy thông tin Model của model trước khi gọi nó: supportedGenerationMethods liệt kê các hành động mà model đó chấp nhận.

Phản hồi (Response)

candidatesarray

Các ứng viên nội dung được tạo.

usageMetadataobject

Thông tin sử dụng token.

Yêu cầu

curl -X POST "https://api.tokenlab.sh/v1beta/models/gemini-2.5-pro:generateContent?key=sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

Lỗi (Errors)

  • 400 INVALID_ARGUMENT: phần thân yêu cầu không hợp lệ, hoặc model không chấp nhận các yêu cầu Gemini.
  • 401 UNAUTHENTICATED: API key bị thiếu hoặc không hợp lệ.
  • 402 RESOURCE_EXHAUSTED: số dư không đủ cho yêu cầu này.
  • 503 UNAVAILABLE: hiện không có tuyến đường nào khả dụng cho model này. Vui lòng thử lại sau.

Đầu vào phương tiện (Media Input)

Đặt phương tiện vào bên trong contents[].parts[] dưới dạng byte Base64 nội tuyến (inlineData hoặc inline_data) hoặc dưới dạng URL https công khai (fileData hoặc file_data). Hình ảnh, âm thanh và video đều được hỗ trợ.

Hình ảnh

Sử dụng byte hình ảnh nội tuyến:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

Sử dụng URL hình ảnh:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}

Âm thanh

Sử dụng URL âm thanh, ở đây sử dụng các tên proto snake_case:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Transcribe and summarize this audio." },
        {
          "file_data": {
            "mime_type": "audio/mpeg",
            "file_uri": "https://example.com/sample.mp3"
          }
        }
      ]
    }
  ]
}

Video

Sử dụng URL video:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Describe this video briefly." },
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://example.com/sample.mp4"
          }
        }
      ]
    }
  ]
}

Phản hồi

Response
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Hello! How can I assist you today?"}
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"}
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 10,
    "totalTokenCount": 15
  }
}

Đếm token và nhúng (Token counting and embeddings)

Đếm Token (POST /v1beta/models/{model}:countTokens) cần có API key và không bị tính phí. Hãy sử dụng số lượng này để lập kế hoạch; chi phí cho một yêu cầu tạo nội dung sẽ dựa trên usageMetadata của phản hồi đó.

Các model nhúng (embedding models) sử dụng Tạo Embedding (POST /v1/embeddings). Chỉ gọi embedContent hoặc batchEmbedContents cho một model mà phản hồi Lấy thông tin Model của nó liệt kê các phương thức đó trong supportedGenerationMethods.

Xác thực

AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Tham số đường dẫn

model*string

Tên model (ví dụ: gemini-2.5-pro)

Tham số truy vấn

key?string

API key (thay thế cho xác thực bằng header)

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

  • "auto"
  • "verified"
  • "official"

Nội dung yêu cầu

application/json

Yêu cầu GenerateContent Gemini gốc. Cả tên ProtoJSON lowerCamelCase và tên proto snake_case gốc đều được chấp nhận và bảo toàn, bao gồm cả các yêu cầu hỗn hợp. Nếu cả hai cách viết của một trường đều có mặt, TokenLab không hợp nhất chúng hoặc chọn ưu tiên cục bộ. Các trường không xác định được chuyển tiếp trên cơ sở nỗ lực tốt nhất.

Phản hồi

application/json

application/json

application/json

application/json

application/json

application/json