Hướng Dẫn Sử Dụng API gpt-image-2

API gpt-image-2 là điểm cuối tạo hình ảnh mới của OpenAI, được ra mắt cùng với ChatGPT Images 2.0 vào ngày 21 tháng 4 năm 2026. Nếu bạn đã gọi API trò chuyện hoặc nhúng của OpenAI, việc thêm chức năng tạo hình ảnh chỉ cần một cấu trúc yêu cầu mới, một khóa API với phạm vi phù hợp và khoảng mười phút.

Hướng dẫn này chỉ tập trung vào API: xác thực, tham số yêu cầu, ví dụ mã bằng ba ngôn ngữ, chế độ tư duy, tạo hàng loạt, xử lý phản hồi, mã lỗi, giới hạn tốc độ và quy trình kiểm thử giúp bạn không lãng phí tín dụng vào các lời nhắc bị lỗi. Để có cái nhìn tổng quan cấp độ sản phẩm về những điểm mới trong ChatGPT Images 2.0, hãy xem bài viết phân tích ChatGPT Images 2.0 của chúng tôi.

Đến cuối cùng, bạn sẽ có các lệnh gọi hoạt động, một bộ sưu tập Apidog có thể tái sử dụng để lặp lại và một bức tranh rõ ràng về chi phí của từng tham số.

nút

Điều kiện tiên quyết

Trước yêu cầu đầu tiên, bạn cần bốn điều:

Một tài khoản OpenAI có quyền truy cập API. Tài khoản nhà phát triển tách biệt với ChatGPT Plus; đăng ký ChatGPT không bao gồm tín dụng API.
Một cấp độ sử dụng có thể thanh toán. gpt-image-2 có sẵn ở Cấp 1 trở lên. Các tài khoản mới bắt đầu ở cấp Miễn phí và phải thêm phương thức thanh toán trước khi các điểm cuối hình ảnh được mở khóa.
Một khóa API với phạm vi images:write. Nên sử dụng khóa có phạm vi dự án hơn là khóa có phạm vi người dùng cho môi trường sản xuất.
Một công cụ kiểm thử xem trước các phản hồi hình ảnh. Terminal curl hoạt động tốt cho yêu cầu đầu tiên; sau đó, hãy sử dụng một ứng dụng khách API thực sự. Chi tiết hơn bên dưới.

Đặt khóa một lần trong shell của bạn để mọi ví dụ trong hướng dẫn này chạy mà không cần chỉnh sửa:

export OPENAI_API_KEY="sk-proj-..."

Điểm cuối và xác thực

gpt-image-2 sử dụng cùng một điểm cuối tạo hình ảnh như mô hình trước:

POST https://api.openai.com/v1/images/generations

Xác thực là một bearer token trong tiêu đề Authorization. Mọi yêu cầu cũng mang một body JSON với ID mô hình, lời nhắc và các tham số đầu ra.

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Một hình ảnh anh hùng sản phẩm sắc nét cho nền tảng kiểm thử API, nền tối",
    "size": "1024x1024",
    "n": 1,
    "quality": "high"
  }'

Nếu lệnh gọi thành công, bạn sẽ nhận được một đối tượng JSON với một mảng data chứa các hình ảnh. Các lỗi sẽ trả về một envelope lỗi OpenAI tiêu chuẩn với một code và một message dễ đọc; bảng lỗi ở phần sau của hướng dẫn này sẽ đề cập đến những lỗi phổ biến.

Tham số yêu cầu

Mọi trường trong body yêu cầu đều thay đổi chi phí bạn phải trả và những gì bạn nhận được. Đây là bản đồ tham số hoàn chỉnh cho gpt-image-2.

Tham số	Loại	Giá trị	Lưu ý
`model`	string	`gpt-image-2`	Bắt buộc.
`prompt`	string	Tối đa 32.000 ký tự	Bắt buộc. Lời nhắc dài hơn sẽ tiêu tốn nhiều token đầu vào hơn.
`size`	string	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Ảnh hưởng đến số lượng token đầu ra.
`quality`	string	`standard`, `high`	`high` có chi phí khoảng gấp đôi nhưng xử lý tốt văn bản và các yếu tố UI.
`n`	integer	1–10	Các yêu cầu theo lô chia sẻ phong cách trên toàn bộ tập hợp.
`thinking`	string	`off`, `low`, `medium`, `high`	Ngân sách suy luận trước khi kết xuất.
`response_format`	string	`url`, `b64_json`	URL hết hạn sau một giờ.
`user`	string	Tự do	Được sử dụng để phát hiện lạm dụng; truyền ID người dùng đã được hash.
`background`	string	`auto`, `transparent`, `opaque`	Đầu ra trong suốt xuất dưới dạng PNG có kênh alpha.
`seed`	integer	Bất kỳ số nguyên 32-bit nào	Kiểm soát lỏng lẻo; cùng một seed cộng cùng một lời nhắc sẽ cho kết quả gần giống, không hoàn toàn giống.

Ba tham số thay đổi chi phí nhiều nhất là size, quality và thinking. Một hình ảnh chất lượng high rộng 2000px với thinking: "high" có thể tốn gấp 4–5 lần so với một hình ảnh 1024x1024 chất lượng standard cơ bản.

Ví dụ Python

SDK chính thức (openai>=1.50.0) bổ sung hỗ trợ gốc cho gpt-image-2:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt=(
        "Một sơ đồ tối giản về quy trình mã ủy quyền OAuth 2.1 với PKCE. "
        "Năm hộp được dán nhãn bằng tiếng Anh: Người dùng, Client, Máy chủ xác thực, Máy chủ tài nguyên, Token. "
        "Văn bản sans-serif sắc nét, nền trắng nhạt, mũi tên màu xanh ngọc."
    ),
    size="1536x1024",
    quality="high",
    n=2,
    thinking="medium",
    response_format="b64_json",
)

out_dir = Path("out")
out_dir.mkdir(exist_ok=True)

for i, image in enumerate(response.data):
    png_bytes = base64.b64decode(image.b64_json)
    (out_dir / f"oauth_{i}.png").write_bytes(png_bytes)

print(f"Đã tạo {len(response.data)} hình ảnh vào {out_dir.resolve()}")

Hai điều đáng lưu ý:

response.data là một danh sách ngay cả khi n=1. Luôn lặp lại.
b64_json dễ sử dụng hơn cho các script cục bộ; url tốt hơn khi bạn chuyển tiếp hình ảnh đến CDN hoặc tải lên S3, vì bạn bỏ qua chu trình giải mã rồi mã hóa lại.

Ví dụ Node.js / TypeScript

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.images.generate({
  model: "gpt-image-2",
  prompt:
    "Mô phỏng giao diện người dùng Dashboard cho một client REST, nhãn viết hoa chữ cái đầu câu, đồ thị tia lửa độ trễ ở góc trên bên phải, bảng màu xám lạnh.",
  size: "1536x1024",
  quality: "high",
  n: 4,
  thinking: "medium",
  response_format: "b64_json",
});

await Promise.all(
  response.data.map(async (image, i) => {
    if (!image.b64_json) return;
    await fs.writeFile(`dash_${i}.png`, Buffer.from(image.b64_json, "base64"));
  }),
);

console.log(`Đã lưu ${response.data.length} hình ảnh`);

Hãy sử dụng SDK chính thức thay vì fetch thô trừ khi bạn có lý do để không. SDK xử lý việc thử lại, tiêu đề idempotency và streaming, đồng thời theo dõi các thay đổi lược đồ đột phá giữa các phiên bản mô hình.

Chế độ tư duy: khi nào nên sử dụng

thinking kiểm soát lượng tính toán mà mô hình dành để lập kế hoạch bố cục trước khi kết xuất. Bốn giá trị, đại khái là:

off: không suy luận. Nhanh nhất, rẻ nhất, tốt nhất cho các lời nhắc sáng tạo tự do mà bố cục không cần phải chính xác.
low: lập kế hoạch nhẹ. Một cài đặt mặc định tốt cho ảnh sản phẩm và hình ảnh hero.
medium: lập kế hoạch nặng hơn. Lựa chọn đúng cho sơ đồ, đồ họa thông tin, slide và bất cứ thứ gì có các yếu tố được đếm (“bốn bảng điều khiển”, “ba mũi tên”).
high: suy luận tối đa. Chỉ đáng giá cho các bố cục đa ngôn ngữ phức tạp hoặc sơ đồ kỹ thuật chặt chẽ; dự kiến độ trễ và chi phí cao hơn đáng kể.

Một quy tắc thực tế: nếu lời nhắc chứa một số, một nhãn hoặc một ràng buộc vị trí, hãy tăng lên một cấp. Nếu nó chỉ nói “một cảnh ấm cúng”, hãy giảm xuống một cấp.

Chế độ tư duy thêm các token suy luận vào hóa đơn ngoài các token đầu ra hình ảnh. Trang giá của OpenAI liệt kê mức giá hiện tại cho mỗi token; hãy dự trù thêm 1,2–2 lần chi phí hình ảnh cơ bản khi bật medium hoặc high.

Tạo hàng loạt

Đặt n > 1 trả về nhiều hình ảnh trong một phản hồi duy nhất chia sẻ bố cục và phong cách. Điều này không giống như gọi điểm cuối n lần song song; điều đó sẽ cho bạn bốn hình ảnh không liên quan. Đầu ra theo lô là nhất quán, phù hợp với cách một nhóm thiết kế lặp lại.

response = client.images.generate(
    model="gpt-image-2",
    prompt="Bốn minh họa hero khác nhau cho một trang đích tài liệu API, bảng màu chung, độ dày đường nét chung.",
    size="1536x1024",
    quality="high",
    n=4,
    thinking="low",
)

Bạn trả tiền cho mỗi hình ảnh, vì vậy n=4 có giá khoảng 4 lần n=1. Lợi ích là sự nhất quán, không phải thông lượng.

Định dạng phản hồi và lưu trữ

Hai định dạng, hai trường hợp sử dụng:

b64_json: hình ảnh được nhúng trực tiếp trong phản hồi. Dễ dàng cho các tập lệnh. Kích thước tải trọng phản hồi tăng nhanh; một PNG chất lượng cao rộng 2000px có thể đẩy kích thước phản hồi vượt quá 3 MB.
url: hình ảnh nằm trên CDN của OpenAI trong một giờ, và bạn tự tải xuống. Tốt hơn cho các hàm không máy chủ có giới hạn kích thước phản hồi và cho các pipeline chuyển tiếp hình ảnh đến bộ nhớ của riêng bạn.

Đối với môi trường sản xuất, hãy tải xuống URL và đẩy nó lên S3, R2 hoặc thùng Cloudflare Images của riêng bạn ngay lập tức. Đừng gửi URL của OpenAI cho người dùng cuối; chúng sẽ hết hạn.

Xử lý lỗi và giới hạn tốc độ

gpt-image-2 trả về các dạng lỗi OpenAI tiêu chuẩn. Đây là những lỗi bạn sẽ gặp phải:

HTTP	`code`	Nguyên nhân	Khắc phục
400	`invalid_request_error`	Kích thước không đúng, tỷ lệ không được hỗ trợ, lời nhắc dài hơn 32k ký tự	Kiểm tra danh sách kích thước và cắt ngắn lời nhắc.
401	`invalid_api_key`	Thiếu hoặc sai khóa	Xuất lại `OPENAI_API_KEY`.
403	`insufficient_quota`	Không đủ tín dụng, hoặc cấp độ Miễn phí	Thêm thanh toán, xác minh cấp độ.
429	`rate_limit_exceeded`	Quá nhiều yêu cầu mỗi phút	Dừng lại một chút với độ trễ ngẫu nhiên; thử lại với `Retry-After`.
429	`image_generation_user_error`	Từ chối do chính sách nội dung	Viết lại lời nhắc.
500	`server_error`	Sự cố tạm thời của OpenAI	Thử lại hai lần với độ trễ lũy thừa.
503	`overloaded`	Tăng đột biến trên toàn khu vực	Đợi và thử lại.

Giới hạn tốc độ trên gpt-image-2 dựa trên cấp độ. Ở Cấp 1, bạn bắt đầu với khoảng 50 yêu cầu mỗi phút; các cấp cao hơn sẽ tăng lên. Luôn đọc các tiêu đề x-ratelimit-remaining-requests và x-ratelimit-remaining-tokens trên mỗi phản hồi và điều tiết trước khi bạn đạt giới hạn.

Các lỗi có thể thử lại trong môi trường sản xuất:

import time
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def generate_with_retry(prompt: str, tries: int = 3):
    delay = 1.0
    for attempt in range(tries):
        try:
            return client.images.generate(
                model="gpt-image-2",
                prompt=prompt,
                size="1024x1024",
                quality="high",
                n=1,
            )
        except RateLimitError:
            time.sleep(delay)
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < tries - 1:
                time.sleep(delay)
                delay *= 2
                continue
            raise
    raise RuntimeError("gpt-image-2 retries exhausted")

Không thử lại lỗi 400, 401 hoặc lỗi 429 liên quan đến chính sách nội dung; những lỗi đó xảy ra có lý do và việc thử lại sẽ lãng phí tín dụng.

Kiểm thử API với Apidog

Việc lặp lại các lời nhắc tạo hình ảnh từ terminal rất chậm: bạn không thể xem kết quả, không thể so sánh các thay đổi tham số và không thể quản lý phiên bản các lời nhắc tốt. Một ứng dụng khách API được xây dựng riêng giải quyết cả ba vấn đề.

Apidog xử lý điểm cuối gpt-image-2 như một yêu cầu hạng nhất. Quy trình làm việc điển hình:

Tạo một yêu cầu mới trong bộ sưu tập OpenAI của bạn, phương thức POST, URL https://api.openai.com/v1/images/generations.
Thêm Authorization: Bearer {{OPENAI_API_KEY}} làm tiêu đề; đặt OPENAI_API_KEY trong biến môi trường để nó không bao giờ nằm trong mã nguồn.
Dán body JSON với lời nhắc của bạn; Apidog xác thực dựa trên đặc tả OpenAPI và hiển thị các lỗi khớp kiểu trước khi bạn gửi.
Nhấn Gửi. Các phản hồi hình ảnh hiển thị trực tiếp; lưu những cái tốt, gắn thẻ những cái xấu, phân nhánh yêu cầu cho các biến thể.
Lưu các môi trường cho thinking: off, thinking: medium và thinking: high để so sánh cùng một lời nhắc trên các cấp độ suy luận khác nhau.

Chức năng so sánh yêu cầu của Apidog là phần quan trọng nhất ở đây. Bạn điều chỉnh một tham số; bạn thấy hình ảnh trước và sau cạnh nhau; bạn lưu kết quả tốt nhất vào một thư viện lời nhắc mà cả nhóm của bạn cùng chia sẻ. Đây là quy trình làm việc mà terminal không thể cung cấp cho bạn.

Nếu bạn đến từ một ứng dụng khách HTTP chung hoặc một không gian làm việc Postman bị lỗi, hãy Tải xuống Apidog và trỏ nó vào khóa OpenAI của bạn; thiết lập mất chưa đến năm phút. Các nhóm đang đánh giá các lựa chọn thay thế cũng có thể đọc hướng dẫn kiểm thử API không dùng Postman của chúng tôi và tổng quan về tiện ích mở rộng Apidog VS Code.

Những sai lầm thường gặp

Một vài sai lầm có thể làm lãng phí tín dụng và thời gian trong tuần đầu tiên sử dụng gpt-image-2.

Sử dụng quality: "standard" cho các lời nhắc nặng văn bản. Chất lượng tiêu chuẩn làm biến dạng văn bản nhỏ. Chuyển sang high khi nhãn, biểu tượng hoặc nội dung UI quan trọng.
Nhắc quá nhiều. 32k ký tự là giới hạn tối đa, không phải mục tiêu. Sau vài trăm token, mô hình bắt đầu bỏ qua các hướng dẫn trước đó. Giữ lời nhắc dưới 500 từ và sử dụng thinking để thực thi các ràng buộc phức tạp.
Mong đợi khả năng tái tạo từ seed. Seed giảm sự biến đổi nhưng không cố định đầu ra. Nếu bạn cần chính xác cùng một hình ảnh, hãy lưu trữ byte; đừng tạo lại.
Gửi URL của OpenAI. Chúng hết hạn sau một giờ. Luôn sao chép vào bộ nhớ của riêng bạn trước khi phục vụ downstream.
Gọi điểm cuối trong một vòng lặp chặt. Tạo hình ảnh chậm. Song song hóa giữa các worker và tuân thủ các tiêu đề giới hạn tốc độ; các vòng lặp chặt tuần tự chỉ xếp hàng và hết thời gian chờ.

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

gpt-image-2 khác với gpt-image-1 ở cấp độ API như thế nào?Cùng điểm cuối, cùng xác thực. Các tham số mới: thinking (off/low/medium/high), các giá trị size bổ sung lên đến 2000px, và n lên đến 10 với phong cách chung. Các tích hợp SDK hiện có vẫn hoạt động sau khi thay đổi ID mô hình; bạn chỉ thêm các tham số mới khi chúng hữu ích. Để biết sự khác biệt đầy đủ, hãy xem tổng quan về ChatGPT Images 2.0.

Cách nhanh nhất để tạo nguyên mẫu tích hợp gpt-image-2 là gì?Tạo một yêu cầu trong Apidog, lưu hai môi trường (tiêu chuẩn so với tư duy), và lặp lại các lời nhắc mà không cần chạm vào mã. Xuất yêu cầu cuối cùng dưới dạng curl hoặc mã SDK khi bạn sẵn sàng thực hiện.

API có hỗ trợ chỉnh sửa hình ảnh hoặc inpainting không?Các điểm cuối chỉnh sửa và biến thể tuân theo cùng một mẫu như thế hệ trước dưới ID mô hình mới. Kiểm tra tài liệu tham khảo mô hình gpt-image-2 để biết lược đồ mới nhất; các tham số cho mặt nạ và hình ảnh đầu vào được ghi lại ở đó.

Tôi có thể sử dụng gpt-image-2 cho đầu ra thương mại không?Có, theo chính sách sử dụng tiêu chuẩn của OpenAI. Bạn sở hữu các hình ảnh được tạo; OpenAI giữ quyền sử dụng đầu vào và đầu ra để giám sát lạm dụng. Các ký tự có thương hiệu và nhân vật công chúng có tên vẫn kích hoạt các hàng rào bảo vệ.

Chi phí cho một khối lượng công việc sản xuất thì sao?Với khoảng 0,21 đô la cho mỗi hình ảnh chất lượng cao 1024x1024 ở chế độ tiêu chuẩn, 10.000 hình ảnh mỗi tháng có chi phí khoảng 2.100 đô la mà không cần chế độ tư duy. Thêm 20–80% cho chế độ tư duy. So sánh điều này với các lựa chọn thay thế tự lưu trữ như hướng dẫn API GLM 5V Turbo và tích hợp Qwen 3.5 Omni của chúng tôi nếu ngân sách quan trọng hơn chất lượng đỉnh cao.

Có lựa chọn thay thế rẻ hơn với khả năng hiển thị văn bản tương tự không?Chưa có ở cùng chất lượng cho văn bản đa ngôn ngữ. Các mô hình mã nguồn mở đã thu hẹp khoảng cách về bố cục nhưng vẫn còn thua kém về các chữ viết CJK và Indic.

nút