Gemini API CLI: ให้ Coding Agent ของคุณเรียกใช้ Gemini สำหรับรูปภาพ วิดีโอ PDF และ Deep Research

Gemini API CLI (gemini-api) คือไคลเอนต์บรรทัดคำสั่งโอเพนซอร์สของ Google สำหรับ Gemini API สร้างขึ้นสำหรับเอเจนต์เขียนโค้ดอย่าง Claude Code, Codex, Cursor และ Antigravity ติดตั้งไบนารี Go เพียงตัวเดียว ตั้งค่า GEMINI_API_KEY แล้วเอเจนต์ของคุณก็จะสร้างรูปภาพ วิดีโอ เสียงพูด และเพลง วิเคราะห์ไฟล์ PDF และไฟล์บันทึกเสียง ถอดเสียงเป็น SRT และเริ่ม Deep Research ในเบื้องหลังได้

ด้านล่างนี้: การติดตั้ง การยืนยันตัวตน คำสั่งที่เอเจนต์ของคุณจะรัน ความแตกต่างจาก Gemini CLI และวิธีจับคู่กับ Apidog CLI ทุกแฟล็กคัดลอกมาจาก gemini-api --help ในเวอร์ชัน 0.4.5 ซึ่งเผยแพร่เมื่อวันที่ 30 ตุลาคม 2026

Gemini API CLI คืออะไร?

Gemini API CLI เป็นไคลเอนต์แบบไม่เก็บสถานะ (stateless) ที่เป็นไบนารีเดียวสำหรับ Interactions API ของ Google แต่ละคำสั่งคือการเรียก HTTP หนึ่งครั้ง: ส่งพรอมป์ต์เข้าไป แล้วได้เส้นทางไฟล์ ข้อความถอดเสียง ผลวิเคราะห์ หรือ ID ของ interaction ออกมา เป็นเครื่องมือที่เอเจนต์ที่มีอยู่ของคุณเรียกใช้เมื่อมีงานที่ต้องใช้ Gemini

หน้าเอกสารอย่างเป็นทางการของ Google เรียกว่า "รีลีสเบต้าโอเพนซอร์สที่พัฒนาควบคู่ไปกับ Interactions API" โค้ดอยู่ที่ google-gemini/gemini-api-cli ภายใต้สัญญาอนุญาต Apache 2.0 และทำงานบน macOS, Linux และ Windows

นี่คือสิ่งที่ gemini-api --help แสดงในเวอร์ชัน 0.4.5 พร้อมโมเดลเริ่มต้นของแต่ละคำสั่ง:

Gemini API CLI กับ Gemini CLI

ชื่อใกล้กันมาก นี่คือความแตกต่าง Gemini CLI (@google/gemini-cli) เป็นเอเจนต์เขียนโค้ดแบบอินเทอร์แอกทีฟ ซึ่งเป็นทางเลือกแทน Claude Code ที่คุณสนทนาด้วย ส่วน Gemini API CLI (gemini-api) ไม่มีลูปเอเจนต์เลย มันเป็นเครื่องมือที่เอเจนต์ตัวอื่นเป็นคนรัน

หากคุณทำงานใน Claude Code หรือ Codex และต้องการใช้โมเดลด้านสื่อและงานวิจัยของ Gemini ภายในเวิร์กโฟลว์นั้น ให้ใช้ gemini-api เป็นรูปแบบเดียวกับ OpenAI CLI เพียงแต่ชี้ไปที่ Google

วิธีติดตั้ง Gemini API CLI

เลือกหนึ่งในสี่วิธีจาก README

macOS และ Linux:

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

Windows (PowerShell):

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

Go:

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

ไบนารีที่คอมไพล์ไว้แล้ว: ดาวน์โหลดไฟล์เก็บถาวรสำหรับแพลตฟอร์มของคุณจาก GitHub Releases ตรวจสอบกับ checksums.txt แล้ววาง gemini-api ไว้ใน PATH ของคุณ เราใช้ไฟล์เก็บถาวร Darwin_arm64 โดย shasum -a 256 -c checksums.txt --ignore-missing แสดงผลเป็น OK

Google เตือนว่าการเปลี่ยนแปลงที่ทำให้ของเดิมพังอาจเกิดขึ้นได้ระหว่างเวอร์ชันไมเนอร์ ดังนั้นควรปักหมุดรีลีสใน CI เอกสารแสดงสคริปต์ติดตั้งโดยวาง GEMINI_VERSION=<release-tag> ไว้ข้างหน้า bash

ตรวจสอบการติดตั้ง:

gemini-api version
# gemini-api 0.4.5

การยืนยันตัวตนของ Gemini API CLI

สร้างคีย์ใน Google AI Studio (คู่มือวิธีขอ Gemini API key ฟรีของเราอธิบายขั้นตอนไว้ทั้งหมด) จากนั้น export คีย์:

export GEMINI_API_KEY="YOUR_API_KEY"

บนเครื่องของคุณเอง คุณสามารถเก็บคีย์ไว้แทนได้:

gemini-api configure --api-key "YOUR_API_KEY"
gemini-api whoami

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

เมื่อยังไม่ได้ตั้งค่าคีย์ gemini-api --help จะแสดงข้อความที่ส่งถึงตัวเอเจนต์เองว่า API key "ต้องถูกสร้างด้วยมือโดยผู้ใช้ใน Google AI Studio ให้หยุดและขอให้ผู้ใช้สร้างขึ้นมา" เอเจนต์ของคุณจะถามคุณแทนที่จะตั้งค่าคีย์ด้วยตัวเอง

ดูตัวอย่างทุกการเรียกด้วย --dry-run

--dry-run จะตรวจสอบแฟล็กและแสดงคำขอโดยปิดบังข้อมูลรับรอง โดยไม่มีการเรียกผ่านเครือข่ายและไม่มีการอ่าน keychain ใช้งานได้ก่อนที่คุณจะตั้งค่าคีย์ ซึ่งเป็นวิธีที่เราใช้ตรวจสอบทุกตัวอย่างในบทความนี้

นี่คือตัวอย่าง dry run จริงของงาน Deep Research ที่รันเบื้องหลัง:

ทุกคำสั่งจะ POST ไปที่ https://generativelanguage.googleapis.com/v1beta/interactions เพิ่ม -o json เพื่อให้ได้ JSON หนึ่งออบเจ็กต์ต่อหนึ่งคำขอทาง stdout ซึ่งเอเจนต์สามารถแยกวิเคราะห์ได้ก่อนที่จะใช้โทเคน

คำสั่ง Gemini API CLI ที่เอเจนต์ของคุณจะรัน

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

gemini-api image "A friendly robot mascot, soft studio lighting" --out ./assets/mascot.jpg
gemini-api image "Add a winter scarf" -i ./assets/mascot.jpg --out ./assets/mascot-winter.jpg

คำสั่งเกี่ยวกับสื่อจะเขียนไฟล์และแสดงเพียงเส้นทางของไฟล์ ดังนั้นเอเจนต์จะจับค่านั้นด้วย $(...) แล้วทำงานต่อไปได้ image ยังรองรับ --aspect-ratio และ --image-size (512, 1K, 2K หรือ 4K) โมเดลเริ่มต้นคือ Nano Banana 2.1 ดูคู่มือ Nano Banana 2.1 APIของเราเพื่อรู้ว่ามันทำอะไรได้ดี

สร้างวิดีโอ เสียงพูด และเพลง

gemini-api video "A slow camera move through a sunlit workshop" --resolution 1080p --out ./assets/
gemini-api tts "Welcome. Let's build something together." --out ./assets/welcome.wav
gemini-api music "Warm ambient music for a product walkthrough" --out ./assets/

วิดีโอใช้เวลานานกว่า ดังนั้น video จะ polling ให้คุณ ใช้ --async เพื่อรับ operation handle ทันที และ --resume <id> เพื่อกลับมา polling ต่อในภายหลัง --resolution มีค่าเริ่มต้นเป็น 720p

วิเคราะห์ PDF รูปภาพ และ URL ของ YouTube

gemini-api analyze -i product-brief.pdf "What should we build first, and why?" > plan.md
gemini-api analyze -i before.png -i after.png "Summarize the visual design changes"

-i/--input ใช้ซ้ำได้และรองรับเส้นทางไฟล์ในเครื่อง, URI แบบ files/<id> หรือ URL ของ YouTube อินพุตแบบอินไลน์จำกัดที่ประมาณ 14 MB (ขนาดดิบ) สำหรับไฟล์ที่ใหญ่กว่า ให้อัปโหลดครั้งเดียวแล้วนำ URI กลับมาใช้ซ้ำ:

FILE_URI=$(gemini-api files upload interview.mp4 --wait --output-format json --jq '.name')
gemini-api analyze -i "$FILE_URI" "List the key action items with timestamps"

ไฟล์ที่อัปโหลดจะถูกลบหลัง 48 ชั่วโมง

ถอดเสียงจากไฟล์เสียงและวิดีโอ

gemini-api transcribe -i interview.mp4 --format srt --out interview.srt

--format รับค่า md (ค่าเริ่มต้น), text, json หรือ srt เพิ่ม --no-speakers หรือ --no-timestamps เพื่อตัดผู้พูดหรือเวลาออกจากเอาต์พุต

รัน Deep Research ในเบื้องหลัง

ID=$(gemini-api agent run "Research battery recycling approaches and cite sources" \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$ID" --stream=false --output-format json

--background จะคืนค่า interaction ID ทันทีแทนที่จะเปิดสตรีมค้างไว้ เอเจนต์จะเก็บ ID นั้นไว้ ไปทำงานอย่างอื่น แล้วกลับมาตรวจสอบด้วย agent status ส่วน agent cancel ใช้หยุดการรัน ผลลัพธ์ help ของ 0.4.5 ยังระบุ deep-research-max-preview-04-2026 และ antigravity-preview-05-2026 เป็น managed agent ด้วย

แฟล็กที่ทำให้ gemini-api ปลอดภัยสำหรับเอเจนต์

นี่คือแฟล็กโกลบอลที่ควรใส่ไว้ในคำสั่งของเอเจนต์คุณ ทั้งหมดมาจาก gemini-api --help-global:

• --agent-mode (หรือ GEMINI_CLI_AGENT_MODE=1): ข้อผิดพลาดแบบ JSON ที่มีโครงสร้างทาง stderr และเอาต์พุต TOON แบบกะทัดรัดทาง stdout
• -o, --output-format: pretty, json, yaml, table หรือ toon
• -q, --jq: กรองเอาต์พุตแบบอินไลน์ เช่น --jq '.id'
• --no-interactive: ไม่มีพรอมป์ต์หรือฟอร์ม TUI ซึ่งเป็นสิ่งที่เอเจนต์แบบไม่มีหน้าจอ (headless) ต้องการ
• --usage: โครงสร้างคำสั่งทั้งหมดในรูปแบบ KDL ที่เครื่องอ่านได้
• --schema (ต่อคำสั่ง): JSON Schema สำหรับเพย์โหลด --body

รหัสออก (exit code) บอกเอเจนต์ว่าเกิดอะไรขึ้นโดยไม่ต้องแยกวิเคราะห์ข้อความ: 0 สำเร็จ, 1 ข้อผิดพลาดขณะรันหรือจาก API, 2 ข้อผิดพลาดในการใช้งานหรือการตรวจสอบความถูกต้อง, 3 การยืนยันตัวตน ข้อควรระวังอย่างหนึ่ง: คำสั่งแบบสตรีมมิ่ง (generate, agent run) ต้องใช้ --stream=false ก่อน -o json หรือ --jq จึงจะให้ผลลัพธ์เดียวที่แยกวิเคราะห์ได้

มอบ Gemini API CLI ให้เอเจนต์เขียนโค้ดของคุณ

README ของ Google มีบล็อกให้คัดลอกไปวางใน AGENTS.md, CLAUDE.md หรือ .cursorrules (ตัดมาเฉพาะบางส่วน):

You have access to gemini-api through the shell.
1. Inspect --help or --usage to choose a command, and --schema when building a --body JSON payload.
2. Preview API calls with --dry-run.
3. For JSON output or --jq on streaming commands, pass --stream=false --output-format json.
4. Capture returned file paths and interaction IDs to continue multi-step tasks.

ตรวจสอบให้แน่ใจว่า GEMINI_API_KEY ไปถึงสภาพแวดล้อมของโปรเซสย่อยของเอเจนต์ จากนั้นสั่งงานตามปกติ: "สร้างแลนดิ้งเพจ ใช้ Gemini ทำรูปมาสคอตและเสียงบรรยาย 20 วินาที และเริ่มรัน Deep Research เกี่ยวกับผลิตภัณฑ์คู่แข่ง" เอเจนต์จะเป็นคนเลือกคำสั่งเอง

สิ่งที่มันทำไม่ได้: เสียงหรือวิดีโอแบบเรียลไทม์ ไม่มีการรองรับ WebSocket ดังนั้น Live API จึงยังต้องใช้ GenAI SDK

ทดสอบ API ที่คุณสร้างด้วย Apidog CLI

gemini-api มอบโมเดลของ Gemini ให้เอเจนต์ของคุณ แต่มันไม่รู้อะไรเลยเกี่ยวกับ API ของคุณเอง ไม่ว่าจะเป็น endpoint /summarize หรือ /thumbnail ที่แอปของคุณห่อไว้รอบ Gemini สภาพแวดล้อมต่างๆ ของมัน หรือ assertion ที่พิสูจน์ได้ว่ารีลีสใหม่ไม่ได้ทำให้อะไรพัง นั่นคืองานของ Apidog CLI และเอเจนต์ตัวเดียวกันก็รันทั้งสองอย่างได้

ตั้งค่าเพียงครั้งเดียว:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

จากนั้นสั่งเอเจนต์ด้วยพรอมป์ต์เดียว:

Use gemini-api to dry-run an analyze call on ./docs/sample-invoice.pdf, then run it for real.
Import ./openapi.yaml into Apidog project <id>, create a test case for POST /v1/invoices/extract
that uploads the same PDF and asserts a 200 and a non-empty "total" field, run it against the
staging environment, and summarize any failures.

เอเจนต์จะตรวจสอบคำตอบของ Gemini ด้วย gemini-api จากนั้นอ่าน schema ของ Apidog ก่อนเขียนเพย์โหลด ตรวจสอบความถูกต้อง และสร้างและรันเทสต์เคส:

apidog import --project <id> --format openapi --file ./openapi.yaml
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> -r cli,json

apidog test-case create --help เตือนถึงกับดักอย่างหนึ่ง: เทสต์เคสต้องมี categoryId ที่ถูกต้อง ดังนั้นให้ลิสต์รายการก่อนด้วย apidog test-case category --project <id> เปลี่ยน -r cli,json เป็น -r junit แล้วบรรทัดเดิมก็รันใน CI ได้ หากคุณใช้ Claude Code เป็นเอเจนต์ เริ่มจาก Apidog CLI ใน Claude Code แพลนฟรีของ Apidog รองรับผู้ใช้สูงสุด 4 คน

คำถามที่พบบ่อย

Gemini API CLI ใช้ฟรีหรือไม่? ตัว CLI เองฟรีและเป็นโอเพนซอร์สภายใต้ Apache 2.0 ทุกการเรียกจะคิดเงินกับ API key ของคุณตามราคา Gemini APIปกติ สำหรับรายละเอียดว่าแพ็กเกจฟรีครอบคลุมอะไรบ้าง ดูคู่มือ Gemini API free tierของเรา

gemini-api เหมือนกับ Gemini CLI ไหม? ไม่เหมือน Gemini CLI เป็นเอเจนต์เขียนโค้ดแบบอินเทอร์แอกทีฟ ส่วน gemini-api เป็นเครื่องมือแบบไม่เก็บสถานะที่เอเจนต์ตัวอื่น สคริปต์ และงานใน CI เรียกใช้เพื่อเข้าถึงโมเดลของ Gemini และ managed agent

ทดสอบคำสั่งโดยไม่มี API key ได้ไหม? ได้ --dry-run จะตรวจสอบคำสั่งและแสดงคำขอแบบตรงทั้งหมดโดยไม่มีการเรียกผ่านเครือข่ายและไม่มีการอ่าน keychain ทุกตัวอย่างในบทความนี้ตรวจสอบด้วยวิธีนั้นบนเวอร์ชัน 0.4.5

จะจัดการไฟล์ที่ใหญ่กว่า 14 MB อย่างไร? รัน gemini-api files upload <file> --wait เก็บค่า files/<id> ที่ได้ และส่งค่านั้นให้ -i ใน analyze, transcribe, generate, image, video หรือ agent run ไฟล์ที่อัปโหลดจะหมดอายุหลัง 48 ชั่วโมง

ควรปักหมุดเวอร์ชันไหม? ควร โดยเฉพาะใน CI Google ระบุว่าการเปลี่ยนแปลงที่ทำให้ของเดิมพังอาจเกิดขึ้นได้ระหว่างเวอร์ชันไมเนอร์ในขณะที่ CLI ยังอยู่ในช่วงเบต้า