Gemini API reference

การอ้างอิง API นี้อธิบาย API มาตรฐาน สตรีมมิง และเรียลไทม์ที่คุณใช้เพื่อโต้ตอบกับโมเดล Gemini ได้ คุณใช้ REST API ได้ในทุก สภาพแวดล้อมที่รองรับคำขอ HTTP โปรดดูคู่มือเริ่มใช้งานฉบับย่อเพื่อดูวิธี เริ่มต้นใช้งานการเรียก API ครั้งแรก หากกำลังมองหาข้อมูลอ้างอิงสำหรับ ไลบรารีและ SDK เฉพาะภาษาของเรา ให้ไปที่ลิงก์สำหรับภาษานั้นใน การนำทางด้านซ้ายใต้ข้อมูลอ้างอิง SDK

Primary endpoints

Gemini API จัดระเบียบตามปลายทางหลักต่อไปนี้

• การสร้างเนื้อหามาตรฐาน (generateContent): ปลายทาง REST มาตรฐานที่ประมวลผลคำขอและแสดง การตอบกลับแบบเต็มของโมเดลในแพ็กเกจเดียว วิธีนี้เหมาะที่สุดสำหรับงานที่ไม่มีการโต้ตอบ ซึ่งคุณสามารถรอผลลัพธ์ทั้งหมดได้
• การสร้างเนื้อหาการสตรีม (streamGenerateContent): ใช้เหตุการณ์ที่เซิร์ฟเวอร์ส่ง (SSE) เพื่อส่งกลุ่มคำตอบให้คุณเมื่อมีการสร้าง ซึ่งจะช่วยให้แอปพลิเคชันต่างๆ เช่น แชทบอท ทำงานได้เร็วขึ้นและโต้ตอบได้มากขึ้น
• Live API (BidiGenerateContent): API ที่อิงตาม WebSocket แบบมีสถานะ สำหรับการสตรีมแบบ 2 ทาง ซึ่งออกแบบมาสำหรับกรณีการใช้งานการสนทนาแบบเรียลไทม์
• โหมดกลุ่ม (batchGenerateContent): ปลายทาง REST มาตรฐานสำหรับการส่งคำขอ generateContent เป็นกลุ่ม
• การฝัง (embedContent): จุดปลาย REST มาตรฐาน ที่สร้างเวกเตอร์การฝังข้อความจากอินพุต Content
• Gen Media API: จุดสิ้นสุดสำหรับการสร้างสื่อด้วยโมเดลเฉพาะทางของเรา เช่น Imagen สำหรับการสร้างรูปภาพ และ Veo สำหรับการสร้างวิดีโอ นอกจากนี้ Gemini ยังมีความสามารถเหล่านี้ในตัว ซึ่งคุณสามารถเข้าถึงได้โดยใช้ generateContent API
• API ของแพลตฟอร์ม: ปลายทางยูทิลิตีที่รองรับความสามารถหลัก เช่น การอัปโหลดไฟล์ และการนับโทเค็น

การตรวจสอบสิทธิ์

คำขอทั้งหมดที่ส่งไปยัง Gemini API ต้องมีส่วนหัว x-goog-api-key พร้อมคีย์ API ของคุณ สร้างได้ด้วยการคลิกเพียงไม่กี่ครั้งใน Google AI Studio

ตัวอย่างคำขอที่มีคีย์ API รวมอยู่ในส่วนหัวมีดังนี้

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"
          }
        ]
      }
    ]
  }'

ดูวิธีการส่งคีย์ไปยัง API โดยใช้ Gemini SDK ได้ที่คำแนะนำการใช้คีย์ API ของ Gemini

การสร้างเนื้อหา

นี่คือปลายทางส่วนกลางสำหรับการส่งพรอมต์ไปยังโมเดล มี 2 ปลายทางสำหรับการสร้างเนื้อหา โดยความแตกต่างที่สำคัญคือวิธีที่คุณรับ การตอบกลับ

• generateContent (REST): รับคำขอและให้ การตอบกลับเดียวหลังจากที่โมเดลสร้างข้อความเสร็จสมบูรณ์แล้ว
• streamGenerateContent (SSE): ได้รับคำขอเดียวกันทุกประการ แต่โมเดลจะสตรีมการตอบกลับเป็นกลุ่มเมื่อมีการสร้าง ซึ่งจะช่วยให้ผู้ใช้ได้รับประสบการณ์การใช้งานแอปพลิเคชันแบบอินเทอร์แอกทีฟที่ดีขึ้น เนื่องจากคุณสามารถแสดงผลลัพธ์บางส่วนได้ทันที

โครงสร้างเนื้อหาคำขอ

เนื้อหาคำขอคือออบเจ็กต์ JSON ที่เหมือนกันสำหรับทั้งโหมดมาตรฐานและโหมดสตรีม และสร้างขึ้นจากออบเจ็กต์หลัก 2-3 รายการ ดังนี้

• ออบเจ็กต์ Content: แสดงถึงการโต้ตอบครั้งเดียวในการสนทนา
• Part ออบเจ็กต์: ข้อมูลภายในContentเทิร์น (เช่น ข้อความหรือรูปภาพ)
• inline_data (Blob): คอนเทนเนอร์สำหรับไบต์สื่อดิบ และประเภท MIME ของไบต์เหล่านั้น

ที่ระดับสูงสุด เนื้อหาคำขอจะมีออบเจ็กต์ contents ซึ่งเป็นรายการออบเจ็กต์ Content แต่ละรายการแสดงถึงการสนทนา ในกรณีส่วนใหญ่สำหรับการสร้างข้อความพื้นฐาน คุณจะมีออบเจ็กต์ Content เพียงรายการเดียว แต่หากต้องการเก็บประวัติการสนทนาไว้ คุณสามารถใช้ออบเจ็กต์ Content หลายรายการได้

ต่อไปนี้คือเนื้อหาคำขอ generateContent ทั่วไป

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
          ]
      }
    ]
  }'

โครงสร้างเนื้อหาการตอบกลับ

เนื้อหาการตอบกลับจะคล้ายกันสำหรับทั้งโหมดการสตรีมและโหมดมาตรฐาน ยกเว้นรายการต่อไปนี้

• โหมดมาตรฐาน: เนื้อหาการตอบกลับจะมีอินสแตนซ์ของ GenerateContentResponse
• โหมดการสตรีม: เนื้อหาการตอบกลับมีสตรีมของอินสแตนซ์ GenerateContentResponse

โดยทั่วไป เนื้อหาของการตอบกลับจะมีออบเจ็กต์ candidates ซึ่งเป็นรายการออบเจ็กต์ Candidate ออบเจ็กต์ Candidate มีออบเจ็กต์ Content ซึ่งมีคำตอบที่สร้างขึ้นซึ่งโมเดลแสดงผล

ตัวอย่างคำขอ

ตัวอย่างต่อไปนี้แสดงให้เห็นว่าคอมโพเนนต์เหล่านี้ทำงานร่วมกันอย่างไรสำหรับคำขอประเภทต่างๆ

พรอมต์แบบข้อความเท่านั้น

พรอมต์ข้อความอย่างง่ายประกอบด้วยอาร์เรย์ contents ที่มีออบเจ็กต์ Content เพียงรายการเดียว ในทางกลับกัน อาร์เรย์ parts ของออบเจ็กต์ดังกล่าวจะมีออบเจ็กต์ Part รายการเดียว ที่มีฟิลด์ 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."
          }
        ]
      }
    ]
  }'

พรอมต์แบบมัลติโมดัล (ข้อความและรูปภาพ)

หากต้องการระบุทั้งข้อความและรูปภาพในพรอมต์ อาร์เรย์ parts ควรมีออบเจ็กต์ Part 2 รายการ ได้แก่ รายการหนึ่งสำหรับข้อความ และอีกรายการหนึ่งสำหรับรูปภาพ inline_data

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?"},
      ]
    }]
  }'

การสนทนาหลายรอบ (แชท)

หากต้องการสร้างการสนทนาที่มีหลายเทิร์น ให้กำหนดอาร์เรย์ contents ด้วยออบเจ็กต์ Content หลายรายการ API จะใช้ประวัติทั้งหมดนี้เป็นบริบท สำหรับคำตอบถัดไป role สำหรับออบเจ็กต์ Content แต่ละรายการควรสลับ ระหว่าง user กับ 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." }
        ]
      }
    ]
  }'

สรุปประเด็นสำคัญ

• Content คือซองจดหมาย ซึ่งเป็นคอนเทนเนอร์ระดับบนสุดสำหรับข้อความ ไม่ว่าจะเป็นจากผู้ใช้หรือโมเดล
• Part ช่วยให้ใช้ข้อมูลหลายรูปแบบได้: ใช้ออบเจ็กต์ Part หลายรายการภายในออบเจ็กต์ Content เดียวเพื่อรวมข้อมูลประเภทต่างๆ (ข้อความ, รูปภาพ, URI ของวิดีโอ ฯลฯ)
• เลือกวิธีการป้อนข้อมูล ดังนี้
  • สำหรับสื่อขนาดเล็กที่ฝังโดยตรง (เช่น รูปภาพส่วนใหญ่) ให้ใช้ Part กับ inline_data
  • สำหรับไฟล์ขนาดใหญ่หรือไฟล์ที่ต้องการนำกลับมาใช้ซ้ำในคำขอต่างๆ ให้ใช้ File API เพื่ออัปโหลดไฟล์และอ้างอิงด้วยส่วน file_data
• จัดการประวัติการสนทนา: สำหรับแอปพลิเคชันแชทที่ใช้ REST API ให้สร้างอาร์เรย์ contents โดยการต่อท้ายออบเจ็กต์ Content สำหรับแต่ละรอบ สลับระหว่างบทบาท "user" และ "model" หากคุณใช้ SDK โปรดดูเอกสารประกอบของ SDK เพื่อดูวิธีที่แนะนำในการจัดการ ประวัติการสนทนา

ตัวอย่างการตอบกลับ

ตัวอย่างต่อไปนี้แสดงให้เห็นว่าคอมโพเนนต์เหล่านี้ทำงานร่วมกันอย่างไรสำหรับคำขอประเภทต่างๆ

คำตอบที่เป็นข้อความเท่านั้น

การตอบกลับด้วยข้อความเริ่มต้นประกอบด้วยอาร์เรย์ candidates ที่มีออบเจ็กต์ content อย่างน้อย 1 รายการซึ่งมีคำตอบของโมเดล

ต่อไปนี้เป็นตัวอย่างการตอบกลับมาตรฐาน

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

ต่อไปนี้คือชุดคำตอบการสตรีม คำตอบแต่ละรายการจะมี responseId ที่เชื่อมโยงคำตอบทั้งหมดเข้าด้วยกัน

{
  "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 แบบสด (BidiGenerateContent) WebSockets API

Live API มี API ที่อิงตาม WebSocket แบบมีสถานะสำหรับการสตรีมแบบ 2 ทางเพื่อ เปิดใช้กรณีการใช้งานการสตรีมแบบเรียลไทม์ ดูรายละเอียดเพิ่มเติมได้ใน คู่มือ Live API และเอกสารอ้างอิง Live API

โมเดลเฉพาะทาง

นอกจากโมเดลตระกูล Gemini แล้ว Gemini API ยังมีปลายทางสำหรับ โมเดลเฉพาะทาง เช่น Imagen Lyria และ โมเดลการฝัง คุณดู คำแนะนำเหล่านี้ได้ในส่วนโมเดล

API ของแพลตฟอร์ม

ส่วนปลายทางที่เหลือจะช่วยให้ใช้ความสามารถเพิ่มเติมร่วมกับปลายทางหลัก ที่อธิบายไว้จนถึงตอนนี้ได้ ดูข้อมูลเพิ่มเติมได้ในหัวข้อ โหมดกลุ่มและ File API ในส่วนคำแนะนำ

ขั้นตอนถัดไป

หากคุณเพิ่งเริ่มต้นใช้งาน โปรดดูคำแนะนำต่อไปนี้ ซึ่งจะช่วยให้คุณเข้าใจโมเดลการเขียนโปรแกรม Gemini API

• การเริ่มต้นใช้งาน Gemini API ฉบับย่อ
• คู่มือโมเดล Gemini

นอกจากนี้ คุณยังดูคำแนะนำเกี่ยวกับความสามารถซึ่งจะแนะนำฟีเจอร์ต่างๆ ของ Gemini API และแสดงตัวอย่างโค้ดได้ด้วย

• การสร้างข้อความ
• การแคชบริบท
• การฝัง