Blog

Cách sử dụng Gemini Omni 1.1 Flash API

Gọi gemini-omni-1.1-flash qua API Tương tác của Google: lấy khóa, thực hiện yêu cầu curl và Python đầu tiên của bạn, xử lý việc truyền tải URI 4MB và lưu cuộc gọi này dưới dạng một bài kiểm tra trong Apidog.

INEZA Felin-Michel

INEZA Felin-Michel

3 tháng 9 2026

Cách sử dụng Gemini Omni 1.1 Flash API

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

Bạn gọi Gemini Omni 1.1 Flash với ID mô hình gemini-omni-1.1-flash thông qua Google’s Interactions API, chứ không phải endpoint generateContent mà bạn sử dụng cho các mô hình văn bản. Đây là điều đầu tiên khiến nhiều người gặp khó khăn. Nếu bạn sao chép một đoạn mã Gemini cho văn bản và đổi tên mô hình, bạn sẽ nhận được lỗi 404.

Hướng dẫn này sẽ đưa bạn từ một terminal trống đến một yêu cầu tạo video đã được kiểm thử. Bạn sẽ nhận được một khóa, thực hiện cuộc gọi đầu tiên bằng curl và Python, tìm hiểu các tham số tồn tại (và danh sách đáng ngạc nhiên những tham số không tồn tại), xử lý các phản hồi lớn và lưu toàn bộ quy trình này dưới dạng một bài kiểm tra có thể lặp lại.

Mô hình này được phát hành rộng rãi (GA) vào ngày 27 tháng 8 năm 2026. Để biết những gì được phát hành cùng với nó, hãy xem điểm mới trong Gemini Omni 1.1 Flash.

Những gì bạn cần trước khi bắt đầu

Lưu khóa dưới dạng biến môi trường thay vì dán trực tiếp vào mã nguồn:

export GEMINI_API_KEY="your_key_here"

Các SDK chính thức sẽ tự động đọc biến đó, giúp giữ bí mật khỏi kho lưu trữ của bạn.

Cuộc gọi tạo video đầu tiên của bạn

Endpoint là một yêu cầu POST đến /v1beta/interactions. Dưới đây là ví dụ bằng curl:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "input": "A marble rolling fast on a chain reaction style track, continuous smooth shot."
  }'

Hai trường: mô hình và đầu vào. Đó là toàn bộ yêu cầu tối thiểu. Phản hồi chứa video được tạo dưới dạng base64 trong output_video.data.

Trong Python, cài đặt SDK bằng pip install google-genai, sau đó:

import base64
from google import genai

client = genai.Client()  # đọc GEMINI_API_KEY từ biến môi trường

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A marble rolling fast on a chain reaction style track, continuous smooth shot.",
)

with open("marble.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))

JavaScript cũng có cấu trúc tương tự với @google/genai:

import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A marble rolling fast on a chain reaction style track, continuous smooth shot.',
});

if (interaction.output_video?.data) {
  fs.writeFileSync('marble.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}

Việc tạo video mất thời gian. Độ trễ tỷ lệ thuận với thời lượng, độ phân giải và tải API hiện tại, vì vậy hãy đặt thời gian chờ (timeout) phía client đủ lớn trước khi bạn cho rằng có lỗi xảy ra.

Kiểm soát độ phân giải và tỷ lệ khung hình

Mọi thứ liên quan đến định dạng đầu ra đều nằm trong response_format:

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A drone shot of a mountain landscape at sunrise.",
    response_format={
        "type": "video",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
    },
)

Các giá trị được chấp nhận:

Trường Giá trị Mặc định
type video video
aspect_ratio 16:9, 9:16 16:9
resolution 360p, 720p, 1080p, 4k 720p
delivery base64 nội tuyến, uri nội tuyến

Tạo bản nháp ở 360p. Nó tạo nhanh hơn tới 60% so với 720p và chi phí chỉ bằng một phần ba, vì vậy mười lăm lần thử prompt bỏ đi của bạn có giá bằng năm lần trước đây. Kết xuất lại cái bạn muốn giữ ở độ phân giải cao hơn. 1080p và 4k là các bản nâng cấp từ các khung hình đã tạo, không phải là kết xuất gốc. Bảng phân tích giá cho thấy chi phí thực tế mỗi giây của từng cấp độ.

Các tham số không tồn tại

Danh sách này quan trọng hơn danh sách trên, bởi vì nếu không bạn sẽ lãng phí cả buổi chiều:

Nếu bạn cần loại trừ thứ gì đó khỏi một cảnh quay, hãy viết điều đó vào chính prompt. Ví dụ trong tài liệu cũng làm điều tương tự: “chỉ sử dụng bản vẽ làm hướng dẫn cho chuyển động, không hiển thị bản vẽ trong video cuối cùng.”

Đầu vào hình ảnh, khung hình chính và tham chiếu

Truyền một danh sách thay vì một chuỗi khi bạn muốn bao gồm phương tiện. Hình ảnh thành video:

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": base64_image, "mime_type": "image/jpeg"},
        {"type": "text", "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"},
    ],
)

Hai hình ảnh trở thành khung hình đầu tiên và khung hình cuối cùng, và mô hình tạo ra chuyển động giữa chúng:

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": first_frame_b64, "mime_type": "image/jpeg"},
        {"type": "image", "data": last_frame_b64, "mime_type": "image/jpeg"},
        {"type": "text", "text": "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky."},
    ],
)

Các tham chiếu video hoạt động theo cùng một cách thông qua Files API, giới hạn ở ba clip, mỗi clip ba giây. Âm thanh trên các clip đó bị bỏ qua; mô hình đọc chúng để nhận biết chuyển động và hình dáng.

Chỉnh sửa đa lượt

Đây là điều tách Omni ra khỏi một endpoint chuyển văn bản thành video thông thường. Tạo một lần, sau đó chỉnh sửa theo kiểu hội thoại bằng cách truyền ID tương tác trước đó:

res1 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A woman playing violin outdoors.",
)

res2 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    previous_interaction_id=res1.id,
    input="Make the violin invisible.",
)

Không cần tải lại, không cần mô tả lại cảnh. Cơ chế tương tự cũng được sử dụng để mở rộng cảnh, được đề cập trong hướng dẫn mở rộng cảnh 40 giây.

Xử lý video dung lượng trên 4MB

Bất kỳ video nào lớn hơn 4MB sẽ được trả về dưới dạng URI thay vì base64 nội tuyến, và tệp cần hoàn tất quá trình xử lý trước khi bạn có thể tải xuống. Đây là lỗi mà hầu hết mọi người gặp phải ở độ phân giải 1080p: trình xử lý của họ đọc output_video.data, không tìm thấy gì và báo cáo một lỗi không rõ nguyên nhân.

Yêu cầu phân phối URI một cách rõ ràng và thăm dò:

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A beautiful sunset.",
    response_format={"type": "video", "delivery": "uri"},
)

video_output = interaction.output_video
file_name = video_output.uri.split("/")[-1]

while True:
    f_info = client.files.get(name=f"files/{file_name}")
    if f_info.state.name == "ACTIVE":
        break
    if f_info.state.name == "FAILED":
        raise RuntimeError("Generation failed.")
    time.sleep(5)

video_bytes = client.files.download(file=video_output.uri)
with open("output.mp4", "wb") as f:
    f.write(video_bytes)

Viết trình xử lý phản hồi của bạn để chấp nhận cả hai định dạng ngay từ đầu. Độ phân giải sẽ thay đổi định dạng bạn nhận được.

Kiểm thử yêu cầu trong Apidog

Khi cuộc gọi hoạt động, vấn đề sẽ thay đổi. Giờ đây, bạn có một endpoint đắt đỏ, chậm, không xác định nằm trong đường dẫn quan trọng của mình, và bạn cần biết khi nào nó thay đổi hành vi. Các lệnh curl ngẫu hứng trong lịch sử shell sẽ không cho bạn biết điều đó.

Thiết lập một lần trong Apidog:

  1. Tạo một dự án và môi trường. Đặt GEMINI_API_KEY và MODEL_ID vào các biến môi trường để khóa không bao giờ xuất hiện trong yêu cầu đã lưu.
  2. Thêm yêu cầu. Gửi POST đến https://generativelanguage.googleapis.com/v1beta/interactions, thân JSON với model và input. Tham chiếu các biến bằng {{MODEL_ID}}.
  3. Tăng thời gian chờ (timeout). Việc tạo video mất nhiều thời gian hơn so với hoàn thành văn bản, và thời gian chờ mặc định của client sẽ cắt bỏ nó.
  4. Thêm các xác nhận (assertions). Kiểm tra mã trạng thái, kiểm tra xem output_video có tồn tại không và kiểm tra định dạng phản hồi bạn mong đợi ở độ phân giải của mình. Đây là xác nhận giúp phát hiện sự chuyển đổi giữa nội tuyến và URI.
  5. Nhân bản cho từng loại tác vụ. Một yêu cầu đã lưu cho mỗi tác vụ chuyển văn bản thành video, hình ảnh thành video và mở rộng. Khi Google phát hành Omni 1.2, bạn chạy ba yêu cầu và biết trong vài phút những gì đã thay đổi.

Apidog không tạo video và nó không phải là một framework AI. Đó là nơi bạn xây dựng yêu cầu, gửi nó và giữ phản hồi theo một tiêu chuẩn bạn đặt ra. Tải xuống Apidog nếu bạn muốn có công cụ này trước khi tăng chi phí.

Các lỗi và cách khắc phục thường gặp

Câu hỏi thường gặp

Toàn bộ quá trình tích hợp bao gồm hai trường bắt buộc cùng với một trình xử lý phản hồi có thể xử lý cả hai dạng phân phối. Hãy thử gọi API ở 360p trước, lưu lại với các xác nhận, sau đó tăng độ phân giải khi bạn tin tưởng vào hệ thống. Đọc tài liệu Omni chính thức để biết danh sách tham số khi chúng phát triển.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống