Gemini API reference

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

จุดสิ้นสุดหลัก

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 และแสดงตัวอย่างโค้ด