Gemini API reference

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

ปลายทางหลัก

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

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

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

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

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

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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 ได้ที่ คู่มือการใช้คีย์ Gemini API

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

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงเนื้อหาคำขอ generateContent ทั่วไป

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.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-3.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-3.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-3.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 คือซองจดหมาย ซึ่งเป็นคอนเทนเนอร์ระดับบนสุดสำหรับการสนทนา 1 รอบ ไม่ว่าจะเป็นจากผู้ใช้หรือโมเดล
• Part ช่วยให้ใช้ได้หลายรูปแบบ โดยใช้ออบเจ็กต์ Part หลายรายการภายในออบเจ็กต์ Content รายการเดียวเพื่อรวมข้อมูลประเภทต่างๆ (ข้อความ, URI รูปภาพ, 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-3.5-flash",
  "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-3.5-flash",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

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

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

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

Platform API

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

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

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

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

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

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