Sebastian Petrus

Posted on Apr 22 • Originally published at apidog.com

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, ra mắt cùng ChatGPT Images 2.0 vào ngày 21/4/2026. Nếu bạn đã từng gọi API trò chuyện hoặc nhúng của OpenAI, việc tích hợp tính năng tạo ảnh chỉ yêu cầu một request mới, một khóa API phù hợp và khoảng mười phút thao tác.

Dùng thử Apidog ngay hôm nay

Bài này tập trung hướng dẫn thực tế: xác thực, tham số yêu cầu, ví dụ code ở 3 ngôn ngữ, chế độ tư duy, batch, xử lý lỗi, giới hạn tốc độ và kiểm thử để tránh lãng phí tín dụng vì prompt lỗi. Để xem tổng quan sản phẩm về ChatGPT Images 2.0, đọc phân tích ChatGPT Images 2.0 của chúng tôi.

Hoàn thành hướng dẫn, 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 để thử lại, và biết cách tối ưu chi phí từng tham số.

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

Trước khi gọi API, chuẩn bị đủ 4 điều sau:

Tài khoản OpenAI có quyền truy cập API (tách biệt với ChatGPT Plus; đăng ký ChatGPT không tự động có tín dụng API).
Cấp độ sử dụng đủ điều kiện thanh toán. gpt-image-2 bắt đầu khả dụng từ Tier 1 trở lên. Tài khoản mới ở Tier Free phải thêm phương thức thanh toán mới mở khóa điểm cuối hình ảnh.
API key với scope images:write. Đề xuất dùng project scope key cho môi trường production.
Công cụ kiểm thử để xem trước phản hồi hình ảnh. Có thể bắt đầu bằng curl trên terminal, sau đó chuyển sang client API chuyên dụng (chi tiết bên dưới).

Đặt khóa vào shell để chạy trực tiếp các ví dụ:

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

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

gpt-image-2 dùng endpoint giống bản cũ:

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

Thêm Bearer token vào header Authorization. Body là JSON gồm model ID, prompt 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 thành công, trả về JSON với mảng data chứa ảnh. Lỗi trả về envelope lỗi chuẩn OpenAI với code và message; xem bảng lỗi bên dưới.

Tham số yêu cầu

Mỗi trường trong body ảnh hưởng trực tiếp đến chi phí và đầu ra. Dưới đây là bảng tham số đầy đủ của 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, prompt càng dài càng tốn token.
`size`	string	`1024x1024`, `1024x1536`, `1536x1024`, `2000x1000`, `1000x2000`, `2000x667`, `667x2000`	Ảnh hưởng số token đầu ra.
`quality`	string	`standard`, `high`	`high` tốn gấp đôi và xử lý tốt text/UI.
`n`	integer	1–10	Batch chia sẻ style toàn bộ tập.
`thinking`	string	`off`, `low`, `medium`, `high`	Ngân sách suy luận trước khi render.
`response_format`	string	`url`, `b64_json`	URL hết hạn sau 1h.
`user`	string	Tự do	Hash user ID để phát hiện lạm dụng.
`background`	string	`auto`, `transparent`, `opaque`	PNG trong suốt có alpha channel.
`seed`	integer	Bất kỳ int 32-bit	Kiểm soát lỏng lẻo; cùng seed + prompt ra gần giống, không hoàn toàn giống.

Ba tham số size, quality và thinking tạo tác động lớn nhất đến chi phí. Ảnh high 2000px kèm thinking: "high" đắt gấp 4–5 lần ảnh 1024x1024 standard.

Ví dụ Python

Dùng SDK chính thức (openai>=1.50.0) để gọi 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()}")

Lưu ý:

response.data luôn là list, kể cả n=1. Luôn lặp.
b64_json tiện cho script cục bộ; url tốt hơn nếu upload ảnh lên CDN/S3.

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`);

Ưu tiên dùng SDK chính thức thay vì fetch thô. SDK tự động xử lý retry, idempotency và streaming, đồng thời bám sát thay đổi schema model.

Chế độ tư duy: khi nào nên dùng

Tham số thinking kiểm soát lượng tính toán mô hình dành cho lập kế hoạch bố cục trước khi render. 4 mức:

off: không suy luận, nhanh, rẻ, thích hợp cho prompt sáng tạo tự do.
low: lập kế hoạch nhẹ, mặc định tốt cho ảnh sản phẩm/hình hero.
medium: lập kế hoạch kỹ, dùng cho sơ đồ, slide, hoặc prompt có nhiều yếu tố đếm được.
high: suy luận tối đa, chỉ nên dùng cho bố cục phức tạp nhiều ngôn ngữ hoặc sơ đồ kỹ thuật cần độ chính xác cao.

Quy tắc thực tế: Nếu prompt có số, nhãn hoặc ràng buộc vị trí, tăng 1 mức. Nếu chỉ mô tả cảnh, giảm cấp.

Chế độ tư duy cộng thêm token suy luận vào hóa đơn ngoài token hình ảnh. Tham khảo giá token OpenAI; dự trù thêm 1,2–2 lần chi phí ảnh cơ bản nếu dùng medium hoặc high.

Tạo hàng loạt

Đặt n > 1 trả về nhiều ảnh trong một response, chia sẻ style và bố cục. Khác biệt hoàn toàn với gọi endpoint song song n lần, vốn sẽ ra ảnh không liên quan nhau. Batch giúp đồng nhất hình ảnh, phù hợp nhóm thiết kế.

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",
)

Trả tiền theo từng ảnh, n=4 giá ~4x 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 use case:

b64_json: ảnh nhúng trong phản hồi, tiện script. Tải trọng lớn, PNG 2000px có thể vượt 3MB.
url: ảnh lưu trên CDN OpenAI 1 giờ, tự tải xuống. Dùng cho serverless function hoặc pipeline chuyển tiếp ảnh tới storage riêng.

Trong production, luôn tải url về và đẩy lên S3, R2 hoặc Cloudflare Images của bạn ngay lập tức. Không gửi url OpenAI cho end user vì sẽ hết hạn.

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

gpt-image-2 trả về lỗi chuẩn OpenAI. Bảng lỗi phổ biến:

HTTP	`code`	Nguyên nhân	Khắc phục
400	`invalid_request_error`	Kích thước/prompt lỗi, vượt 32k ký tự	Kiểm tra kích thước, rút ngắn prompt.
401	`invalid_api_key`	Thiếu/sai API key	Xuất lại `OPENAI_API_KEY`.
403	`insufficient_quota`	Hết tín dụng hoặc Free tier	Thêm payment, kiểm tra tier.
429	`rate_limit_exceeded`	Quá nhiều request/phút	Thử lại sau, đọc header `Retry-After`.
429	`image_generation_user_error`	Lỗi do policy nội dung	Viết lại prompt.
500	`server_error`	Lỗi server OpenAI	Thử lại với delay tăng dần.
503	`overloaded`	Tăng đột biến khu vực	Chờ rồi thử lại.

Giới hạn tốc độ phụ thuộc tier. Tier 1: ~50 request/phút, tier cao hơn tăng lên. Luôn đọc header x-ratelimit-remaining-requests và x-ratelimit-remaining-tokens để điều tiết request.

Xử lý retry lỗi tạm thời trong production:

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 retry lỗi 400, 401 hoặc 429 policy; các lỗi này sẽ lãng phí tín dụng nếu lặp lại.

Kiểm thử API với Apidog

Lặp lại prompt trên terminal rất tốn thời gian: không xem được ảnh, khó so sánh thay đổi tham số, không quản lý version prompt tốt. Client API chuyên dụng giải quyết triệt để các vấn đề này.

Apidog hỗ trợ gpt-image-2 như một API hạng nhất. Quy trình thực tế:

Tạo request mới trong collection OpenAI, dùng POST, URL https://api.openai.com/v1/images/generations.
Thêm header Authorization: Bearer {{OPENAI_API_KEY}}; set biến môi trường OPENAI_API_KEY để bảo mật.
Dán JSON body prompt vào; Apidog kiểm tra schema dựa trên OpenAPI và báo lỗi type mismatch trước khi gửi.
Nhấn Gửi. Ảnh trả về hiển thị trực tiếp; lưu những ảnh tốt, gắn tag ảnh lỗi, clone request nhanh cho biến thể mới.
Lưu nhiều môi trường cho thinking: off, medium, high để so sánh cùng prompt dưới các mức tư duy khác nhau.

Chức năng so sánh của Apidog là điểm mạnh: bạn chỉnh một tham số, thấy ảnh trước–sau cạnh nhau, lưu lại prompt tối ưu cho nhóm dùng chung. Terminal không thể cung cấp trải nghiệm này.

Nếu bạn đang dùng HTTP client hoặc workspace Postman cũ, hãy Tải xuống Apidog và kết nối với OpenAI key; thiết lập dưới 5 phút. Các nhóm cân nhắc phương án thay thế có thể đọc hướng dẫn kiểm thử API không dùng Postman và tổng quan tiện ích mở rộng Apidog VS Code của chúng tôi.

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

Dùng quality: "standard" cho prompt chứa nhiều text. Standard làm méo text nhỏ, nên chuyển high khi xuất nhãn, icon, nội dung UI.
Prompt quá dài. 32k ký tự là giới hạn, không phải mục tiêu. Sau vài trăm token, model bỏ qua hướng dẫn trước. Giữ prompt < 500 từ, dùng thinking để enforce constraint.
Kỳ vọng seed tái tạo hoàn toàn. Seed chỉ giảm biến động, không cố định đầu ra. Muốn giống ảnh cũ, hãy lưu byte ảnh, không tạo lại.
Gửi url OpenAI cho user. URL hết hạn sau 1 giờ. Luôn tải về storage riêng trước khi phân phối downstream.
Gọi endpoint trong vòng lặp chặt. Ảnh tạo chậm. Hãy song song hóa giữa các worker, tuân thủ header giới hạn tốc độ; vòng lặp tuần tự dễ bị timeout.

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

gpt-image-2 khác gpt-image-1 ở điểm nào (API)? Endpoint và xác thực như nhau. Thêm tham số thinking (off/low/medium/high), giá trị size mới lên đến 2000px, n lên đến 10 với style đồng bộ. SDK hiện tại dùng bình thường khi thay model ID, chỉ bổ sung tham số khi cần. Xem chi tiết trong tổng quan ChatGPT Images 2.0.

Cách nhanh nhất để tạo prototype tích hợp gpt-image-2? Tạo request trong Apidog, lưu 2 môi trường (standard vs thinking), lặp lại prompt không cần code. Khi sẵn sàng, export sang curl hoặc SDK code.

API hỗ trợ edit/inpainting không? Các endpoint edit/variation theo mẫu cũ, chỉ thay model ID. Kiểm tra reference model gpt-image-2 để xem schema mới; tham số mask và input image đã có.

Có thể dùng gpt-image-2 cho mục đích thương mại? Có, theo policy chuẩn OpenAI. Bạn sở hữu ảnh tạo ra; OpenAI giữ quyền dùng input/output để giám sát abuse. Tên thương hiệu, nhân vật công chúng vẫn bị guardrail.

Chi phí dự kiến cho production workload? Ảnh 1024x1024 chất lượng cao, chế độ standard: ~$0.21/ảnh. 10.000 ảnh/tháng khoảng $2.100 chưa tính tư duy. Thêm 20–80% nếu bật thinking. So sánh với self-hosted như API GLM 5V Turbo hoặc tích hợp Qwen 3.5 Omni nếu ngân sách hạn chế.

Có lựa chọn rẻ hơn với khả năng xử lý text tương đương? Hiện chưa có lựa chọn mã nguồn mở chất lượng ngang về text đa ngữ. Model open source đã cải thiện layout nhưng vẫn thua về font chữ CJK và Indic.