Hướng dẫn sử dụng API GPT-Image-2.6

API GPT-Image-2.6 tạo và chỉnh sửa ảnh thông qua hai mô hình của OpenAI là gpt-image-2.6-flare và gpt-image-2.6-sunburst. Gửi prompt đến POST /v1/images/generations kèm API key, sau đó giải mã b64_json từ phản hồi. Phiên bản 2.6 bổ sung markup ảnh, đầu ra SVG và GIF, cùng tham số complexity.

Hướng dẫn này bao gồm xác thực, tạo ảnh lần đầu, chỉnh sửa bằng markup, xuất SVG, và các thiết lập quality cùng complexity. Bài viết chỉ tập trung vào những điểm mới, vì vậy hãy đọc hướng dẫn API gpt-image-2.5 của chúng tôi để tìm hiểu về streaming và công cụ Responses API, cùng bài giải thích về ChatGPT Images 2.6 để nắm toàn bộ thông tin phát hành. Mọi request dưới đây đều được chúng tôi xây dựng dựa trên tài liệu của OpenAI ngày 5 tháng 11 năm 2026. Chúng tôi chưa chạy thử với key thật, nên hãy kiểm tra trước khi đưa vào sử dụng.

Tổng quan về API GPT-Image-2.6

Đơn giá lấy từ trang giá của OpenAI. Cả hai mô hình có cùng mức giá trên mỗi token, nên hãy chọn dựa trên tốc độ và độ chính xác khi chỉnh sửa.

Flare hay Sunburst: nên gọi mô hình nào?

Chọn Flare cho việc lặp nhanh và tạo ảnh hằng ngày. OpenAI cho biết mô hình này có thể trả về ảnh chỉ trong sáu giây ở chất lượng low, và cải thiện bố cục cho poster và ảnh sản phẩm. Chọn Sunburst cho công việc chi tiết và chỉnh sửa nhiều lần, khi OpenAI tuyên bố mô hình này cho độ nhất quán tốt hơn ở chất lượng medium hoặc high.

Đây là những tuyên bố của OpenAI, không phải kết quả đánh giá độc lập. Bài so sánh Flare và Sunburst cho phiên bản 2.5 của chúng tôi sẽ giải thích rõ sự khác biệt này.

Xác thực và thiết lập

Bạn cần chuẩn bị ba thứ trước lần gọi đầu tiên:

1. Tạo API key trong dashboard của OpenAI và export thành OPENAI_API_KEY.
2. Hoàn tất Xác minh tổ chức API nếu tổ chức của bạn cần. OpenAI cho biết bạn có thể phải làm việc này trước khi dùng được các mô hình GPT Image.
3. Cài jq cho các ví dụ curl, hoặc gói openai cho Python.

Nếu ứng dụng của bạn phục vụ người dùng riêng lẻ, hãy gửi thêm safety_identifier đã băm với tối đa 128 ký tự. Tham số này thay thế cho user đã bị deprecated.

Tạo ảnh đầu tiên của bạn

Request này dùng Flare ở chất lượng low, phù hợp cho bản nháp.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A minimal poster for a developer meetup, with the words SHIP IT in bold type",
    "size": "1024x1536",
    "quality": "low",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > poster.png

Lệnh tương tự trong Python:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.6-sunburst",
    prompt="A product shot of a ceramic mug on a walnut desk, soft morning light",
    size="1536x1024",
    quality="medium",
    extra_body={"complexity": "low"},
)

Path("mug.png").write_bytes(base64.b64decode(result.data[0].b64_json))

Chúng tôi truyền complexity qua extra_body để lệnh gọi không phụ thuộc vào việc phiên bản SDK của bạn có hỗ trợ nó như một tham số có tên hay không. Các mô hình GPT Image luôn trả về base64, nên đừng gửi response_format, và cũng đừng tìm trường url.

Hướng dẫn của OpenAI nói rằng hãy đọc đối tượng usage trong phản hồi để đo lượng token sử dụng. Tài liệu API reference lại mô tả trường này chỉ dành cho gpt-image-1, dù phản hồi mẫu có bao gồm nó, vì vậy hãy xác nhận nó xuất hiện trong phản hồi 2.6 của bạn trước khi xây dựng hệ thống theo dõi chi phí dựa trên nó.

Chỉnh sửa ảnh bằng markup

Markup cho mô hình biết cần thay đổi ở đâu. Bạn gửi ảnh gốc, một PNG trong suốt chứa các vòng tròn hoặc nét vẽ của bạn, và một prompt mô tả nội dung chỉnh sửa.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "images": [{"image_url": "https://your-bucket.example/kitchen.png"}],
    "markup": {"image_url": "https://your-bucket.example/vase-overlay.png"},
    "prompt": "Recolor the vase inside the red circle to solid cobalt blue. Keep everything else unchanged. Remove the red circle.",
    "quality": "medium",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > vase.png

Request JSON dùng mảng images và một đối tượng markup chứa đúng một trong hai trường image_url hoặc file_id. image_url có thể là URL HTTPS hoặc data URL base64. Request multipart thì dùng file upload thay thế, và hướng dẫn tạo ảnh có phiên bản Python cho cách này.

Lớp phủ (overlay) có những quy tắc nghiêm ngặt:

• Sau khi xoay hướng, nó phải khớp với chiều rộng và chiều cao của ảnh đầu tiên.
• Nó phải chứa các pixel trong suốt, nên đừng làm phẳng nó lên ảnh.
• Nó áp dụng cho ảnh đầu vào đầu tiên. Các ảnh khác chỉ đóng vai trò tham chiếu.
• Mỗi ảnh trong hai ảnh có thể chứa tối đa 16.777.216 pixel, và file overlay không được vượt quá 50 MB.
• Bạn không thể kết hợp markup với mask hoặc prompt_rewriter.

Hãy yêu cầu mô hình xóa chú thích, như ví dụ của chính OpenAI. Markup có chi phí như mọi chỉnh sửa khác. Responses API không hỗ trợ nó, nên hãy dùng mask ở đó.

Xuất SVG

Đặt output_format thành svg trên endpoint generations cho icon, logo và hình minh họa cần đường dẫn có thể chỉnh sửa.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "A flat two-color wheat logo for a bakery called Field and Flour",
    "output_format": "svg",
    "quality": "medium",
    "n": 1
  }' | jq -er '.data[0].b64_json' | base64 --decode > logo.svg

API trước tiên render một ảnh tham chiếu, do quality kiểm soát, rồi viết SVG từ ảnh đó. Các byte sau khi giải mã là XML UTF-8, không chứa script, tài nguyên bên ngoài hay raster nhúng.

Có bốn giới hạn:

• n phải bằng 1.
• Streaming, ảnh từng phần, output_compression và prompt_rewriter đều không hoạt động.
• Endpoint edits không thể xuất SVG, và cũng không nhận SVG làm đầu vào raster.
• Đối tượng svg tùy chọn dùng để chọn mô hình soạn thảo, nhưng chỉ khi tài khoản của bạn có tính năng chọn mô hình SVG. Nếu không, hãy bỏ qua nó.

Bạn phải trả phí hai lần: đơn giá ảnh cho ảnh tham chiếu và đơn giá của mô hình soạn thảo cho các token của nó. API reference liệt kê một đối tượng svg_usage riêng cho phần thứ hai, nên hãy ghi log nó.

Tạo GIF

API trả về một GIF hoàn chỉnh, không phải sprite sheet. Thêm ba trường vào request generations:

{
  "model": "gpt-image-2.6-flare",
  "prompt": "A small orange robot waves, blinks and returns to its starting pose. Make it loop.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "size": "auto"
}

Giải mã b64_json theo cách tương tự và lưu thành .gif. Hãy kiểm tra hai điều trước:

• Giới hạn số frame. Hướng dẫn nói frame_count chạy từ 2 đến 64. API reference lại nói từ 2 đến 16. Hãy giữ ở mức 16 hoặc thấp hơn cho đến khi bạn đã thử nghiệm với giá trị cao hơn.
• Quyền truy cập. Tài liệu reference nói đầu ra GIF yêu cầu quyền truy cập vào bản preview GIF cho mô hình đã chọn, trong khi hướng dẫn không đề cập điều này. Một request GIF bị từ chối có thể là vấn đề quyền truy cập, chứ không phải payload sai.

Đầu ra GIF không hỗ trợ streaming, ảnh từng phần hay output_compression tùy chỉnh, và endpoint edits không thể trả về nó. OpenAI không công bố công thức tính phí riêng cho GIF, nên hãy chạy thử một lượng nhỏ và kiểm tra hóa đơn trước khi mở rộng quy mô.

Thiết lập quality và complexity

quality kiểm soát độ chi tiết khi render và quyết định chi phí token. complexity kiểm soát mức độ lập kế hoạch của mô hình trước khi render, và việc thay đổi nó không phát sinh phí riêng.

Hãy đặt complexity trong mọi request. Giá trị mặc định là high, nhưng OpenAI khuyến nghị low cho hầu hết các chỉnh sửa. Hướng dẫn cảnh báo rằng thiết lập cao hơn có thể làm tăng độ trễ và gây ra những thay đổi không mong muốn.

Quality cũng quyết định hóa đơn đầu ra của bạn. Bảng này dùng công cụ tính của OpenAI cho ảnh 1024x1024, đọc ngày 5 tháng 11, và chưa bao gồm token đầu vào:

Khoảng cách giữa medium và high chỉ khoảng một xu, nên hãy so sánh cả hai. Tab Batch trên trang giá chưa liệt kê 2.6, nên đừng mặc định rằng ưu đãi batch của 2.5 vẫn áp dụng.

Xử lý lỗi và timeout

Phân loại lỗi dựa trên việc thử lại có giúp ích hay không:

Dùng error.code làm căn cứ kiểm tra ổn định, và ghi log request ID. moderation_details chứa moderation_stage và categories thô, những thứ này nên nằm trong log của bạn, không phải trong thông báo hiển thị cho người dùng. Đặt timeout phía client trên hai phút, vì OpenAI nói rằng prompt phức tạp có thể mất ngần ấy thời gian.

Để coding agent của bạn kiểm thử bằng Apidog CLI

Coding agent của bạn có thể biến những request và giới hạn này thành một bộ test với Apidog CLI. Thiết lập một lần:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Sau đó đưa cho Claude Code, Codex hoặc Cursor một prompt:

In Apidog project <id>, add POST /v1/images/generations and POST /v1/images/edits
on https://api.openai.com. Read the bearer token from OPENAI_API_KEY.
Create test cases for gpt-image-2.6-flare at low quality and low complexity:
1. PNG generation: assert status 200 and data[0].b64_json exists.
2. SVG generation: assert status 200 and output_format equals svg.
3. GIF with frame_count 6: assert status 200 and output_format equals gif.
4. SVG with n set to 2: assert a 4xx status and that error.message exists.
5. GIF with frame_count 17: record the status, because OpenAI's docs disagree.
Put them in a test suite named "GPT-Image-2.6", run it against environment
<envId>, and summarize every failure.

Agent đọc từng schema, kiểm tra payload, rồi viết và chạy bộ test:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <id> --file endpoint.json
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 cli-schema validate test-suite-create --file suite.json
apidog test-suite create --project <id> --file suite.json
apidog test-suite run <suiteId> --project <id> -e <envId> \
  --env-var "OPENAI_API_KEY=$OPENAI_API_KEY" --on-error continue -r cli,json

Case 5 sẽ xác định giới hạn frame cho tài khoản của bạn, và case 3 cho biết bạn có quyền truy cập GIF hay không. Các case thành công sẽ tạo ra ảnh thật và bị tính phí, nên hãy giữ quality ở mức thấp. Đổi sang -r junit để chạy bộ test trong pipeline CI, và xem hướng dẫn thiết lập Claude Code để biết chi tiết về agent.

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

Tên mô hình của API GPT-Image-2.6 là gì? gpt-image-2.6-flare và gpt-image-2.6-sunburst. API reference chưa liệt kê bản snapshot theo ngày cho chúng, khác với các mô hình 2.5.

API GPT-Image-2.6 có giá bao nhiêu? Token ảnh có giá 8 USD cho mỗi 1M token đầu vào và 30 USD cho mỗi 1M token đầu ra. Một ảnh 1024x1024 tốn khoảng 0,025 USD chi phí đầu ra ở mức low và khoảng 0,053 USD ở mức high, chưa tính token đầu vào.

Tôi có nên chuyển từ gpt-image-2.5 không? Hãy chuyển nếu bạn cần SVG, GIF hoặc complexity. Nhưng hãy kiểm tra chi phí trước: một ảnh low dùng khoảng 4,2 lần lượng token so với 2.5, và các mô hình 2.6 chưa có giá Batch được liệt kê.

Tôi có thể dùng complexity trên endpoint edits không? Có. OpenAI khuyến nghị low cho hầu hết các chỉnh sửa.

Tôi có thể biến một ảnh đã upload thành GIF qua API không? Không. Endpoint edits không trả về GIF hay SVG, nên cả hai định dạng này đều bắt đầu từ một prompt văn bản trên endpoint generations.

API có trả về URL không? Không. Các mô hình GPT Image luôn trả về base64 trong b64_json, nên bạn phải tự giải mã và lưu file.