Image API — tạo và chỉnh sửa ảnh

Gọi gpt-image-2 để tạo và chỉnh sửa ảnh qua ZetaAPI. Tương thích OpenAI Images, kèm ví dụ curl / Python / Node, chỉnh sửa multipart, kích thước đầu ra, tính phí và timeout.

Cập nhật 2026-07-26

Các endpoint ảnh của ZetaAPI tương thích hoàn toàn với OpenAI Images API — dùng API key hiện có để tạo hoặc chỉnh sửa ảnh với gpt-image-2, không cần đổi SDK. Muốn thử ngay trên trình duyệt, mở Image Playground trong console; trang này hướng dẫn gọi từ code.

Base URL & xác thực

Request tạo ảnh đi tới domain riêng cho ảnh:

https://image.zetaapi.ai

Mọi request đều mang Authorization: Bearer sk-xxxxx (cùng key với chat).

Vì sao ảnh có domain riêng: tạo ảnh là request non-streaming kéo dài — chờ upstream render có thể mất tới 240 giây. Domain chính api.zetaapi.ai nằm sau CDN và sẽ ngắt kết nối ở khoảng 120 giây. Bạn nhận về một lỗi, nhưng ảnh vẫn đã được tạo ở upstream và vẫn bị tính phí. Domain ảnh kết nối thẳng tới origin nên không có giới hạn này — đừng tự động retry request tạo ảnh trên domain chính.

Domain này chỉ phục vụ /v1/images/generations và /v1/images/edits. Mọi thứ khác — bao gồm cả phần tạo ảnh độ phân giải cao bằng Gemini bên dưới, vốn đi qua /v1/chat/completions — vẫn dùng https://api.staging.cosmos-router.com.

Nếu bạn từng nhận thông báo di chuyển trước đây của chúng tôi, trong đó ghi direct.zetaapi.ai: domain đó vẫn còn hiệu lực và tương đương.

Kiểm tra domain có hoạt động không

Mọi request tới domain này ngoài hai endpoint ở trên — kể cả đường dẫn gốc / — đều bị ngắt kết nối mà không có phản hồi. curl sẽ báo Empty reply from server hoặc HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR, chứ không phải 404. Đây là chính sách bảo mật có chủ đích và không có nghĩa là domain bị lỗi.

Để xác nhận domain hoạt động, hãy POST thẳng vào endpoint (không cần key, không tốn quota):

curl -i -X POST https://image.zetaapi.ai/v1/images/generations \
  -H "Content-Type: application/json" -d '{}'

Nhận được 401 Authorization Required nghĩa là DNS, TLS và gateway đều bình thường — nó chỉ đang yêu cầu API key của bạn.

Endpoint

Tạo ảnh

Tham số

curl

curl https://image.zetaapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red panda coding at night, neon rim light, 16:9 cinematic banner",
    "n": 1
  }'

Python (openai SDK)

import base64
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://image.zetaapi.ai/v1")

resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red panda coding at night, neon rim light, 16:9 cinematic banner",
    n=1,
)

with open("out.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

Node.js (openai SDK)

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxx",
  baseURL: "https://image.zetaapi.ai/v1",
});

const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a red panda coding at night, neon rim light, 16:9 cinematic banner",
  n: 1,
});

writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));

Phản hồi

{
  "created": 1730000000,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 }
}

Mặc định trả về b64_json (PNG mã hóa base64). Truyền "response_format": "url" để nhận link ảnh thay thế.

Kích thước đầu ra

Hãy điều khiển tỉ lệ khung hình bằng prompt, không phải bằng tham số size.

gpt-image-2 luôn dựng ảnh với ngân sách cố định khoảng 1,57 megapixel. Bạn không thể nâng con số này — viết “4K” hay “3840x2160” trong prompt cũng không cho thêm pixel. Thứ bạn có thể điều khiển là hình dạng: mô tả tỉ lệ khung hình trong prompt và nó được tuân thủ chính xác.

Phạm vi hỗ trợ là 1:3 đến 3:1. Các tỉ lệ phổ biến khớp chính xác (16:9 → 1672 × 941); gần giới hạn sẽ lấy kích thước khả dụng gần nhất — yêu cầu 1:3 đo được ~1:2,9. Mọi tỉ lệ đều có cùng chi phí vì số pixel không đổi.

Tham số size được chấp nhận để các SDK OpenAI vẫn chạy được, nhưng bị bỏ qua — size: "1024x1536" với prompt trung tính vẫn trả về ảnh vuông. Nếu cần kích thước pixel chính xác, hãy tạo ở tỉ lệ gần nhất rồi resize tại máy bạn.

Cần độ phân giải thực sự cao hơn? Giới hạn pixel này đến từ nhà cung cấp thượng nguồn của gpt-image-2 và chúng tôi không đổi được — hãy dùng Gemini 3 Pro Image, dựng được tới 17 MP.

Độ phân giải cao: Gemini 3 Pro Image

Với nhu cầu cần pixel thật — in ấn, banner lớn, hình nền — hãy dùng gemini-3-pro-image-preview. Độ phân giải chọn được và được tuân thủ chính xác. Kích thước dưới đây đo khi không truyền aspect_ratio — nếu đặt tham số này, chiều rộng/cao sẽ đổi nhưng vẫn cùng bậc pixel:

Model này không dùng được trên /v1/images/* — nhà cung cấp thượng nguồn chỉ mở qua chat completions. Hai điểm khác với Images API:

1. Gọi POST /v1/chat/completions và truyền độ phân giải trong extra_body.
2. Ảnh trả về dưới dạng Markdown data-URI bên trong choices[0].message.content, không phải data[0].b64_json.

curl https://api.staging.cosmos-router.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "messages": [{"role": "user", "content": "Generate an image: a red panda coding at night, neon rim light"}],
    "extra_body": {"google": {"image_config": {"image_size": "4K"}}}
  }'

import base64, re
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://api.staging.cosmos-router.com/v1")

resp = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=[{"role": "user", "content": "Generate an image: a red panda coding at night"}],
    # SDK gộp extra_body vào cấp cao nhất của body, nhưng gateway đọc trường
    # `extra_body` ở cấp cao nhất — nên phải bọc thêm một lớp nữa.
    # Thiếu lớp này request sẽ âm thầm rơi về 1K.
    extra_body={"extra_body": {"google": {"image_config": {"image_size": "4K"}}}},
)

# content: "Image generated successfully.\n![image](data:image/png;base64,iVBOR...)"
content = resp.choices[0].message.content
m = re.search(r"base64,([A-Za-z0-9+/=]+)", content or "")
if not m:
    raise RuntimeError(f"no image in response (refused or plain text): {content!r}")
with open("out.png", "wb") as f:
    f.write(base64.b64decode(m.group(1)))

Lưu ý:

• Tính phí theo token như chat: ảnh 2K khoảng 1.120 image token (≈ $0,06), ảnh 4K khoảng 2.000 (≈ $0,09). Đơn giá xem trang giá.
• Cùng khối image_config còn hỗ trợ aspect_ratio (ví dụ "16:9").
• Không streaming và chậm hơn gpt-image-2 ở độ phân giải thấp: thường 20–60 giây, đôi khi lâu hơn ở 4K. Lưu ý: request đi theo đường chat, nơi ngân sách byte đầu tiên của gateway là 90 giây — 4K với prompt phức tạp có thể nhận 504. Hãy thử lại hoặc hạ xuống 2K.
• PNG 4K nặng ~19MB trước base64, tức JSON response khoảng 25MB — hãy chắc client và proxy phía trước chấp nhận kích thước đó.

Xuất 4K trong console

Không cần viết code: mở console → Playground tạo ảnh và đặt Độ phân giải thành “4K (cạnh dài >= 3840)”. Cả tab tạo ảnh và chỉnh sửa ảnh đều hỗ trợ.

• Kết quả trả về luôn ở 4K — bấm “Tải xuống” ở góc trên bên phải để lưu
• Mức này mỗi lần chạy tạo một ảnh
• Cần Chrome hoặc Edge bản tương đối mới trên desktop; trên trình duyệt không hỗ trợ, mục này sẽ bị làm mờ

Đây là tính năng của console. Khi gọi gpt-image-2 qua API, đầu ra vẫn là khoảng 1,57 MP như mô tả ở trên.

Chỉnh sửa ảnh (edits)

Chỉnh sửa dùng multipart/form-data: tải ảnh gốc (bắt buộc) + mask tùy chọn (vùng trong suốt sẽ được vẽ lại):

curl https://image.zetaapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxx" \
  -F model=gpt-image-2 \
  -F 'prompt=đổi ô vuông ở giữa thành màu xanh' \
  -F image=@source.png \
  -F mask=@mask.png

• Ảnh gốc + mask tổng cộng ≤ 14MB (vượt quá trả về 413)
• Định dạng: png / jpeg
• size hoạt động giống như ở generations — được chấp nhận nhưng bị bỏ qua; xem Kích thước đầu ra

Tính phí, độ trễ & timeout

• Tính phí theo lượt: mỗi lần tạo / chỉnh sửa đều trừ hạn mức thật của key; hệ số xem trang giá. Chỉnh sửa đưa toàn bộ ảnh gốc vào input nên input token cao hơn rõ rệt.
• Độ trễ: tạo ảnh thường mất 20–60 giây, nhưng prompt phức tạp (đa góc nhìn, render siêu chi tiết) hoặc giờ cao điểm có thể vượt 3 phút. Đặt timeout client ≥ 300 giây — gateway chỉ trả 504 sau 240 giây không nhận được byte đầu tiên từ upstream, ngắt sớm hơn chỉ là chờ vô ích. Sửa ảnh (/v1/images/edits) cần nhiều hơn: timeout client thường tính từ lúc bắt đầu upload, trong khi ngân sách 240 giây của gateway chỉ bắt đầu sau khi ảnh gốc upload xong — hãy đặt ≥ thời gian upload + 300 giây (an toàn là ≥ 400 giây).
• Phản hồi ảnh không streaming — kết quả đầy đủ trả về một lần.

Mã lỗi

Nhất quán với các endpoint khác. Thường gặp:

Danh sách đầy đủ trong API Reference.

Thêm

• Thử trực tiếp → Image Playground trong console
• API chung → API Reference
• Tính phí → trang giá