Gemini API CLI

Gemini API CLI (gemini-api) เป็นไคลเอ็นต์บรรทัดคำสั่งแบบไม่เก็บสถานะและไม่มีทรัพยากร Dependency ซึ่งสร้างขึ้นสำหรับ AI Agent ที่มีสิทธิ์เข้าถึง Shell (และใช้งานได้จากสคริปต์และ CI) จากนั้น Agent การเขียนโค้ดจะสร้างข้อความที่สร้างขึ้นและสื่อ วิเคราะห์ไฟล์ และมอบหมายงานให้กับAgent ที่ได้รับการจัดการโดย Gemini ได้ โดยจะทำงานร่วมกับ Antigravity, Claude Code, Codex, Cursor, OpenClaw, Hermes หรือสภาพแวดล้อมของ Shell ใดก็ได้

ทุกฟีเจอร์จะทำงานเป็นคำสั่ง Shell มาตรฐานใน Interactions API เรียกใช้คำสั่งเดียวกันจากกระบวนการย่อยของ Agent, เทอร์มินัล หรือไปป์ไลน์ CI

# 1. Install on macOS or Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

# 2. Set your API key
export GEMINI_API_KEY="YOUR_API_KEY"

# 3. Generate media, analyze a file, or launch a background managed agent
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false

เลือกเครื่องมือ Gemini ที่เหมาะสม

ใช้ gemini-api เมื่อ Agent หรือสคริปต์ต้องเรียกใช้ Gemini โดยตรงจาก Shell โดยไม่ต้องเพิ่มโค้ด SDK ลงในโปรเจ็กต์ ใช้ SDK และการตั้งค่าเอเจนต์การเขียนโค้ดเมื่อคุณสร้าง Gemini ลงในแอปพลิเคชัน

วิธีการทำงาน

การเรียก REST แบบข้อมูลดิบและ CLI แบบอินเทอร์แอกทีฟมักทำให้เกิดปัญหากับเอเจนต์การเขียนโค้ด สื่อ Base64 จะเติมเต็มหน้าต่างบริบท พรอมต์แบบอินเทอร์แอกทีฟจะบล็อกกระบวนการย่อย และข้อมูลฝึกฝนที่ล้าสมัยจะทำให้เกิดแฟล็กที่ผิดพลาด

ตัวเลือกการออกแบบ 4 รายการที่ช่วยให้ gemini-api เชื่อถือได้สำหรับ Agent มีดังนี้

• การค้นหาสคีมาแบบออฟไลน์: ส่ง --usage เพื่อพิมพ์โครงสร้างคำสั่ง (ใน KDL) หรือ --schema เพื่อพิมพ์สคีมา JSON สำหรับคำขอ --body
• ไฟล์ในดิสก์ เส้นทางใน stdout: คำสั่งสื่อและการถอดเสียงจะเขียนไฟล์ลงในดิสก์และพิมพ์เฉพาะเส้นทางเอาต์พุต โดยเก็บข้อมูลไบนารีไว้นอกบริบท
• การทดสอบและการแสดงผลที่มีโครงสร้าง: --dry-run จะตรวจสอบอินพุต ปกปิดข้อมูลเข้าสู่ระบบ และแสดงตัวอย่างคำขอ HTTP แบบออฟไลน์ ส่ง -o json, -o toon หรือ --jq สำหรับเอาต์พุตที่เครื่องอ่านได้ เพิ่ม --agent-mode เพื่อแสดงข้อผิดพลาด JSON ที่มีโครงสร้างใน stderr และตรวจสอบรหัสออกเพื่อจัดการกับความล้มเหลว คำสั่งจะไม่แสดงข้อความแจ้ง เว้นแต่คุณจะส่ง --interactive
• ไม่มีสถานะโดยค่าเริ่มต้น: คำสั่งจะไม่เก็บสถานะในเครื่องที่ซ่อนไว้ เชื่อมโยงงานแบบหลายขั้นตอนอย่างชัดเจนด้วย --previous-interaction-id, URI ของ files/<id> ที่อัปโหลด หรือรหัสการโต้ตอบในเบื้องหลัง

เมื่อใช้ -o json คำสั่งสื่อจะยังคงเขียนไฟล์ลงในดิสก์และพิมพ์ข้อมูลเมตาไปยัง stdout ดังนี้

{
  "kind": "image",
  "mime_type": "image/jpeg",
  "path": "/path/to/project/assets/db-icon.jpg",
  "response_id": "v1_...",
  "size_bytes": 2914159,
  "status": "completed"
}

เริ่มต้นใช้งาน

ติดตั้ง CLI, ใส่ gemini-api ใน PATH, ตั้งค่า GEMINI_API_KEY และเพิ่มกฎการใช้งานให้กับ Agent การเขียนโค้ด

1. ติดตั้งไบนารี

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash

iwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex

go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest

2. กำหนดค่าการตรวจสอบสิทธิ์และยืนยัน

สร้างคีย์ API ใน Google AI Studio (ดูคีย์ API) ตั้งค่า GEMINI_API_KEY ใน Shell และสภาพแวดล้อมกระบวนการย่อยของ Agent ดังนี้

export GEMINI_API_KEY="YOUR_API_KEY"

ในเวิร์กสเตชันภายใน คุณสามารถบันทึกคีย์ในพวงกุญแจของระบบปฏิบัติการ (พวงกุญแจ macOS, Linux Secret Service หรือ Windows Credential Manager) ส่ง --no-keyring เพื่อจัดเก็บคีย์ใน ~/.config/gemini-api/config.yaml แทน:

# Save to your OS keychain (or run gemini-api configure --interactive)
gemini-api configure --api-key "YOUR_API_KEY"

# Check the active credential source, then preview a request offline
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run

3. ป้อนคำสั่งสำหรับ Agent

เพิ่มข้อมูลโค้ดนี้ลงใน AGENTS.md, CLAUDE.md, .cursorrules หรือพรอมต์ของระบบของโปรเจ็กต์เพื่อให้ Agent การเขียนโค้ดทราบวิธีใช้ gemini-api

## Gemini API CLI (`gemini-api`)

You have access to `gemini-api` through the shell. Use it to generate text or media (images, speech, music, video), analyze documents and recordings, or run and manage Gemini managed agents.

1. Run `gemini-api --help` or `gemini-api --usage` to choose a command, and `gemini-api <command> --schema` before building a `--body` JSON payload.
2. Preview unfamiliar or complex calls offline with `--dry-run -o json`.
3. For a single JSON result or `--jq` filtering on `generate` or `agent run`, pass `--stream=false -o json`.
4. To chain multi-step workflows, capture the output paths that media and transcription commands print to stdout, and the `id` values returned by `generate` or `agent run`.

จากนั้นป้อนพรอมต์ Agent การเขียนโค้ดตามปกติ ดังนี้

Build a landing page for our developer tool. Use Gemini to generate a hero
illustration and a 15-second welcome voiceover, and start a background Deep
Research agent to compare competing CLI onboarding flows. Wire the assets and
findings into the page.

คำสั่ง

เรียกใช้ gemini-api --help เพื่อแสดงรายการคำสั่งทั้งหมด หรือ gemini-api explore เพื่อเรียกดูคำสั่งแบบอินเทอร์แอกทีฟ

เวิร์กโฟลว์

คำสั่งแต่ละรายการจะใช้โมเดลที่เหมาะกับงานนั้นๆ โดยค่าเริ่มต้น พูดว่า --model (-m) เพื่อเลือกโมเดลอื่น เรียกใช้ gemini-api models เพื่อแสดงตัวเลือกที่มี

การสร้างและแก้ไขรูปภาพ

Agent ที่สร้าง UI สำหรับเว็บหรืออุปกรณ์เคลื่อนที่สามารถสร้างตัวยึดตำแหน่ง ไอคอน และรูปภาพหลักด้วย Nano Banana ส่งเส้นทางที่สร้างขึ้นกลับมาพร้อมกับ -i เพื่อแก้ไขรูปภาพ:

# Generate a 16:9 image at 2K resolution (512, 1K, 2K, or 4K) and capture its path
HERO_PATH=$(gemini-api image "Friendly robot mascot in a sunlit workshop, space on left for headline" \
  --aspect-ratio 16:9 \
  --image-size 2K \
  --out ./public/images/hero.jpg)

# Edit the generated image
gemini-api image "Add a winter scarf and soft snowfall outside the window" \
  -i "$HERO_PATH" \
  --out ./public/images/hero-winter.jpg

ส่ง -i หลายครั้งเพื่อรวมรูปภาพอ้างอิง เช่น ตัวละครและไกด์สไตล์

การสังเคราะห์เสียงพูด

gemini-api tts สังเคราะห์เสียง WAV 24 kHz สำหรับคิว UI, ตัวอย่างการช่วยเหลือพิเศษ และคำแนะนำแบบบรรยาย เสียงเริ่มต้นคือ Kore เลือกเสียงอื่นด้วย --voice สำหรับการสนทนาที่มีผู้พูด 2 คน ให้ติดป้ายกำกับแต่ละเทิร์นในพรอมต์และจับคู่ผู้พูดกับเสียง ดังนี้

gemini-api tts "Build succeeded. All integration tests passed." \
  --voice Aoede \
  --out ./public/audio/build-ok.wav

gemini-api tts "Alice: Welcome to the release walkthrough! Bob: Let's look at what shipped today." \
  --multi-speaker "Alice=Kore,Bob=Puck" \
  --out ./public/audio/release-intro.wav

เพลงและวิดีโอ

แต่งแทร็กต้นฉบับด้วย Lyria และสร้างคลิป MP4 ด้วย Gemini Omni โดยทำดังนี้

gemini-api music "Warm ambient synth and acoustic guitar background loop, 95 BPM" \
  --out ./public/audio/bg-loop.mp3

gemini-api video "A drone shot of a mountain landscape at sunrise." \
  --aspect-ratio 16:9 \
  --resolution 1080p \
  --out ./public/video/mountain-sunrise.mp4

โดยค่าเริ่มต้น คำสั่ง video จะรอให้การสร้างเสร็จสิ้นและเขียนไฟล์ MP4 ลงในดิสก์ ส่ง --async เพื่อแสดงรหัสการโต้ตอบทันที แล้วเรียกใช้ gemini-api video --resume <id> --out <path> ในภายหลัง ส่ง -i เพื่อสร้างภาพเคลื่อนไหวจากรูปภาพที่มีอยู่

การสร้างข้อความ

gemini-api generate ส่งข้อความถึง stdout:

gemini-api generate "Write a one-paragraph welcome message for new users of a note-taking app."

เพิ่ม --stdin เพื่อส่งข้อความไปยังพรอมต์ ส่งต่อ --previous-interaction-id เพื่อ โต้ตอบต่อจากก่อนหน้านี้

การวิเคราะห์และการถอดเสียงเอกสาร

analyze ตอบคำถามเกี่ยวกับ PDF, สเปรดชีต, ภาพหน้าจอ, ไฟล์เสียงและวิดีโอ รวมถึง URL สาธารณะของ YouTube transcribe เขียนข้อความถอดเสียงที่จัดรูปแบบแล้ว (md, text, json หรือ srt) ลงในดิสก์

gemini-api analyze -i ./docs/product-brief.pdf "List the open questions and who owns each one." > open-questions.md

gemini-api transcribe -i ./fixtures/customer-call.mp4 --format srt --out ./fixtures/customer-call.srt

ส่ง -i หลายครั้งไปยัง analyze เพื่อเปรียบเทียบไฟล์ เช่น ภาพหน้าจอก่อนและหลัง

gemini-api จะส่งไฟล์ในเครื่องแบบอินไลน์ได้สูงสุด 14 MB (20 MB หลังจากเข้ารหัส Base64) สำหรับไฟล์ขนาดใหญ่ ให้อัปโหลดครั้งเดียวด้วย files upload --wait และใช้ URI files/<id> ที่แสดงผลซ้ำ:

FILE_URI=$(gemini-api files upload ./recordings/all-hands.mp4 --wait)

gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format json --out ./recordings/all-hands.json

เรียกใช้และจัดการ Agent

Agent การเขียนโค้ดสามารถมอบหมายงานวิจัยหลายขั้นตอนหรือ Sandbox ให้กับAgent ที่จัดการโดย Gemini เช่น Agent ของ Deep Research ส่ง --background --stream=false เพื่อรับรหัสการโต้ตอบทันทีแทนที่จะเปิดสตรีมค้างไว้

# Launch a Deep Research job in the background and capture its interaction ID
RESEARCH_ID=$(gemini-api agent run "Compare open-source vector index benchmarks and cite primary papers." \
  --agent deep-research-preview-04-2026 \
  --background \
  --stream=false \
  --jq '.id')

# Check status or fetch the finished result while continuing other work
gemini-api agent status "$RESEARCH_ID" -o json

เรียกใช้ gemini-api agent cancel <id> เพื่อหยุดงานที่กำลังทำงานอยู่ นอกจากนี้ คุณยังเปิดAgent ของ Antigravity ในแซนด์บ็อกซ์ระยะไกลด้วย agent run หรือจัดการAgent ที่กำหนดเองด้วย agent create, list, get และ delete ได้ด้วย ดูสภาพแวดล้อมเพื่อกำหนดค่า Agent ของแซนด์บ็อกซ์

เนื้อหาคำขอที่กำหนดเอง

สำหรับตัวเลือกที่ไม่มี Flag เฉพาะ ให้ส่งเพย์โหลด JSON ของ Interactions API แบบข้อมูลดิบพร้อม --body (แบบอินไลน์หรือเป็น @file.json) ส่ง --body เพื่อตั้งค่าสคีมา response_format, เครื่องมือการเรียกใช้ฟังก์ชัน, generation_config หรือ "store": false เรียกใช้ gemini-api <command> --schema ก่อนเพื่อตรวจสอบช่องที่ถูกต้อง

# Inspect the JSON Schema for the request body
gemini-api generate --schema > generate-schema.json

# Return schema-constrained JSON and skip storing the interaction
cat logs.txt | gemini-api generate "Extract every error message from these logs." \
  --stdin \
  --body '{
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {"errors": {"type": "array", "items": {"type": "string"}}},
        "required": ["errors"]
      }
    },
    "store": false
  }'

--body ผสานรวมกับแฟล็กคำสั่ง หากทั้ง 2 รายการตั้งค่าคีย์เดียวกัน คำสั่งจะดำเนินการไม่สำเร็จพร้อมรหัสออก 2 เพื่อให้อินพุตที่ขัดแย้งกันดำเนินการไม่สำเร็จอย่างรวดเร็ว

โค้ดสำหรับออก

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

เรียกใช้ gemini-api --help-global เพื่อแสดงรายการแฟล็กส่วนกลางที่ใช้ร่วมกันโดยทุกคำสั่ง (การตรวจสอบสิทธิ์ เอาต์พุต เครือข่าย และการวินิจฉัย)

ข้อจำกัด

• คำสั่งสตรีมมิง (generate และ agent run) ต้องใช้ --stream=false เมื่อรวมกับ -o json หรือ --jq เพื่อแสดงผลออบเจ็กต์การตอบกลับ JSON รายการเดียว
• อินพุตไฟล์ -i ในบรรทัดจำกัดข้อมูลไฟล์ดิบไว้ที่ 14 MB (เพย์โหลดคำขอ 20 MB รวมถึงการเข้ารหัส Base64) อัปโหลดไฟล์ขนาดใหญ่ด้วย gemini-api files upload Files API จะลบไฟล์ที่อัปโหลดหลังจากผ่านไป 48 ชั่วโมง
• gemini-api รองรับคำขอ HTTP มาตรฐาน, การสตรีม SSE และการโพลแบบไม่พร้อมกัน แต่ไม่รองรับ WebSocket แบบ 2 ทิศทาง สำหรับการสตรีมเสียงและวิดีโอแบบเรียลไทม์ ให้ใช้ Live API กับ Google GenAI SDK

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

• การตั้งค่า Agent การเขียนโค้ด
• Interactions API
• Agent ที่ได้รับการจัดการของ Gemini
• gemini-api-cli บน GitHub