Hãy dùng thử Lyria 3, mô hình tạo nhạc mới của chúng tôi có khả năng tạo ra âm thanh nổi có độ trung thực cao từ văn bản và hình ảnh đầu vào.

Gemini API reference

Tài liệu tham khảo API này mô tả các API tiêu chuẩn, API truyền trực tuyến và API theo thời gian thực mà bạn có thể sử dụng để tương tác với các mô hình Gemini. Bạn có thể sử dụng các API REST trong mọi môi trường hỗ trợ yêu cầu HTTP. Hãy tham khảo Hướng dẫn bắt đầu nhanh để biết cách bắt đầu với lệnh gọi API đầu tiên. Nếu bạn đang tìm tài liệu tham khảo cho các thư viện và SDK dành riêng cho ngôn ngữ của chúng tôi, hãy chuyển đến đường liên kết cho ngôn ngữ đó trong trình đơn điều hướng bên trái trong phần Tài liệu tham khảo về SDK.

Điểm cuối chính

Gemini API được sắp xếp xung quanh các điểm cuối chính sau:

Tạo nội dung tiêu chuẩn (generateContent): Một điểm cuối REST tiêu chuẩn xử lý yêu cầu của bạn và trả về phản hồi đầy đủ của mô hình trong một gói duy nhất. Đây là lựa chọn tốt nhất cho các tác vụ không mang tính tương tác, trong đó bạn có thể chờ kết quả đầy đủ.
Tạo nội dung truyền trực tuyến (streamGenerateContent): Sử dụng Sự kiện do máy chủ gửi (SSE) để gửi các phần phản hồi cho bạn khi các phần này được tạo. Điều này mang lại trải nghiệm nhanh hơn và mang tính tương tác hơn cho các ứng dụng như chatbot.
API Trực tiếp (BidiGenerateContent): Một API dựa trên WebSocket có trạng thái để truyền trực tuyến hai chiều, được thiết kế cho các trường hợp sử dụng đàm thoại theo thời gian thực.
Chế độ hàng loạt (batchGenerateContent): Một điểm cuối REST tiêu chuẩn để gửi các lô yêu cầu generateContent.
Truy vấn nhúng (embedContent): Một điểm cuối REST tiêu chuẩn tạo vectơ truy vấn nhúng văn bản từ Content đầu vào.
API Gen Media: Các điểm cuối để tạo nội dung nghe nhìn bằng các mô hình chuyên dụng của chúng tôi, chẳng hạn như Imagen để tạo hình ảnh, và Veo để tạo video. Gemini cũng có sẵn các tính năng này mà bạn có thể truy cập bằng API generateContent.
API nền tảng: Các điểm cuối tiện ích hỗ trợ các tính năng cốt lõi như tải tệp lên và đếm mã thông báo.

Xác thực

Tất cả các yêu cầu gửi đến Gemini API đều phải bao gồm tiêu đề x-goog-api-key có khoá API của bạn. Tạo một khoá bằng vài cú nhấp trong Google AI Studio.

Sau đây là một yêu cầu mẫu có khoá API trong tiêu đề:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

Để biết hướng dẫn về cách truyền khoá API của bạn đến Gemini API bằng SDK Gemini, hãy xem hướng dẫn Sử dụng khoá API Gemini.

Tạo nội dung

Đây là điểm cuối trung tâm để gửi câu lệnh đến mô hình. Có 2 điểm cuối để tạo nội dung, điểm khác biệt chính là cách bạn nhận phản hồi:

generateContent (REST): Nhận một yêu cầu và cung cấp một phản hồi duy nhất sau khi mô hình hoàn tất toàn bộ quá trình tạo.
streamGenerateContent (SSE): Nhận chính xác yêu cầu đó, nhưng mô hình sẽ truyền trực tuyến các phần phản hồi khi các phần này được tạo. Điều này mang lại trải nghiệm người dùng tốt hơn cho các ứng dụng mang tính tương tác vì cho phép bạn hiển thị kết quả một phần ngay lập tức.

Cấu trúc nội dung yêu cầu

Nội dung yêu cầu là một đối tượng JSON màgiống hệt nhau cho cả chế độ tiêu chuẩn và chế độ truyền trực tuyến, đồng thời được tạo từ một số đối tượng cốt lõi:

Content đối tượng: Đại diện cho một lượt duy nhất trong cuộc trò chuyện.
Part đối tượng: Một phần dữ liệu trong lượt Content (như văn bản hoặc hình ảnh).
inline_data (Blob): Một vùng chứa cho các byte nội dung nghe nhìn thô và loại MIME của chúng.

Ở cấp cao nhất, nội dung yêu cầu chứa một đối tượng contents, là danh sách các đối tượng Content, mỗi đối tượng đại diện cho các lượt trong cuộc trò chuyện. Trong hầu hết các trường hợp, để tạo văn bản cơ bản, bạn sẽ có một đối tượng Content duy nhất, nhưng nếu muốn duy trì nhật ký trò chuyện, bạn có thể sử dụng nhiều đối tượng Content.

Sau đây là nội dung yêu cầu generateContent điển hình:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

Cấu trúc nội dung phản hồi

Nội dung phản hồi tương tự cho cả chế độ truyền trực tuyến và chế độ tiêu chuẩn, ngoại trừ những điểm sau:

Chế độ chuẩn: Nội dung phản hồi chứa một thực thể của GenerateContentResponse.
Chế độ truyền trực tuyến: Nội dung phản hồi chứa một luồng các GenerateContentResponse thực thể.

Ở cấp cao, nội dung phản hồi chứa một đối tượng candidates, là danh sách các đối tượng Candidate. Đối tượng Candidate chứa một đối tượng Content có phản hồi được tạo trả về từ mô hình.

Ví dụ về yêu cầu

Các ví dụ sau đây cho thấy cách các thành phần này kết hợp với nhau cho nhiều loại yêu cầu.

Câu lệnh chỉ có văn bản

Một câu lệnh văn bản đơn giản bao gồm một mảng contents có một đối tượng Content duy nhất. Đến lượt mảng parts của đối tượng đó chứa một đối tượng Part duy nhất có trường text.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a single paragraph."
          }
        ]
      }
    ]
  }'

Câu lệnh đa phương thức (văn bản và hình ảnh)

Để cung cấp cả văn bản và hình ảnh trong một câu lệnh, mảng parts phải chứa 2 đối tượng Part: một cho văn bản và một cho inline_data hình ảnh.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

Cuộc trò chuyện nhiều lượt (trò chuyện)

Để xây dựng một cuộc trò chuyện nhiều lượt, bạn hãy xác định mảng contents bằng nhiều đối tượng Content. API sẽ sử dụng toàn bộ nhật ký này làm ngữ cảnh cho phản hồi tiếp theo. role cho mỗi đối tượng Content phải luân phiên giữa user và model.

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

Những điểm chính cần ghi nhớ

Content là vùng chứa: Đây là vùng chứa cấp cao nhất cho một lượt tin nhắn, cho dù là từ người dùng hay mô hình.
Part cho phép đa phương thức: Sử dụng nhiều đối tượng Part trong một đối tượng Content để kết hợp nhiều loại dữ liệu (văn bản, hình ảnh, URI video, v.v.).
Chọn phương thức dữ liệu:
- Đối với nội dung nghe nhìn nhỏ, được nhúng trực tiếp (như hầu hết hình ảnh), hãy sử dụng Part có inline_data.
- Đối với các tệp lớn hơn hoặc các tệp bạn muốn sử dụng lại trên nhiều yêu cầu, hãy sử dụng File API để tải tệp lên và tham chiếu tệp đó bằng một phần file_data.
Quản lý nhật ký trò chuyện: Đối với các ứng dụng trò chuyện sử dụng API REST, hãy tạo mảng contents bằng cách thêm các đối tượng Content cho mỗi lượt, luân phiên giữa vai trò "user" và "model". Nếu bạn đang sử dụng SDK, hãy tham khảo tài liệu về SDK để biết cách quản lý nhật ký cuộc trò chuyện được đề xuất.

Ví dụ về phản hồi

Các ví dụ sau đây cho thấy cách các thành phần này kết hợp với nhau cho nhiều loại yêu cầu.

Phản hồi chỉ có văn bản

Phản hồi văn bản mặc định bao gồm một mảng candidates có một hoặc nhiều đối tượng content chứa phản hồi của mô hình.

Sau đây là ví dụ về phản hồi tiêu chuẩn:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

Sau đây là chuỗi phản hồi truyền trực tuyến. Mỗi phản hồi chứa một responseId liên kết phản hồi đầy đủ với nhau:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

API Trực tiếp (BidiGenerateContent) API WebSocket

API Trực tiếp cung cấp một API dựa trên WebSocket có trạng thái để truyền trực tuyến hai chiều nhằm cho phép các trường hợp sử dụng truyền trực tuyến theo thời gian thực. Bạn có thể xem lại hướng dẫn về API Trực tiếp và tài liệu tham khảo API Trực tiếp để biết thêm thông tin.

Mô hình chuyên dụng

Ngoài nhóm mô hình Gemini, Gemini API còn cung cấp các điểm cuối cho các mô hình chuyên dụng như Imagen, Lyria và mô hình truy vấn nhúng. Bạn có thể xem các hướng dẫn này trong phần Mô hình.

API nền tảng

Phần còn lại của các điểm cuối cho phép sử dụng thêm các tính năng với các điểm cuối chính được mô tả cho đến nay. Hãy xem các chủ đề Chế độ hàng loạt và File API trong phần Hướng dẫn để tìm hiểu thêm.

Bước tiếp theo

Nếu bạn mới bắt đầu, hãy xem các hướng dẫn sau đây. Các hướng dẫn này sẽ giúp bạn hiểu mô hình lập trình Gemini API:

Bạn cũng có thể muốn xem các hướng dẫn về tính năng. Các hướng dẫn này giới thiệu nhiều tính năng của Gemini API và cung cấp các ví dụ về mã: