Tạo ảnh bằng API

Dùng một khóa API và SDK OpenAI quen thuộc để tạo ảnh từ mô tả, hoặc sửa một ảnh có sẵn. Bạn chọn kích thước; giá tính theo từng ảnh và độ phân giải.

Điểm cần nhớ

Lấy model ảnh từ GET /v1/models: model có images.generations trong endpoints.
Ảnh trả về dạng base64 (b64_json) hoặc link (url); hãy lưu ngay vì API không giữ ảnh.
Giá = giá mỗi ảnh × hệ số độ phân giải (1K ×1, 2K ×2, 4K ×4 với model chia mức) × số ảnh.
Sửa ảnh gửi multipart/form-data tới /v1/images/edits, với trường image.
Request lỗi không bị tính phí.

Tạo ảnh đầu tiên#

Gửi model và prompt tới POST /v1/images/generations. API tương thích OpenAI Images, nên SDK openai dùng được ngay: chỉ cần đổi base_url và khóa API.

Ảnh trả về trong data, dạng base64 (b64_json) hoặc đường link (url) tùy model. Đoạn code dưới đây tạo một ảnh và lưu thành fox.png.

POST /v1/images/generations

curl https://api.xpncore.com/v1/images/generations \
  -H "Authorization: Bearer $XPNCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "IMAGE_MODEL_ID",
    "prompt": "A watercolor fox reading a book under a maple tree, soft morning light",
    "n": 1,
    "size": "1024x1024"
  }' | jq -r '.data[0].b64_json' | base64 --decode > fox.png

200 OK · application/json

{
  "created": 1759550400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..."
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 1290,
    "total_tokens": 1314
  }
}

usage chỉ có khi model báo số token. Header x-routing-request-id của response là mã request; hãy gửi kèm mã này khi cần hỗ trợ.

Chọn model ảnh#

Gọi GET /v1/models bằng khóa API của bạn. Model tạo ảnh có images.generations trong mảng endpoints; model sửa ảnh được có thêm images.edits.

Dùng đúng id của model trong trường model.
Giá mỗi ảnh của từng model có ở trang Model & giá.
Gửi tới model không tạo ảnh sẽ bị từ chối với lỗi 422.

Tham số request#

Body là JSON. Các trường khác (ví dụ style, background, output_format) được chuyển nguyên cho model; model không hiểu trường nào thì bỏ qua hoặc báo lỗi.

modelstringBắt buộc: ID model lấy từ GET /v1/models.
promptstringBắt buộc: Mô tả ảnh cần tạo. Càng cụ thể càng tốt: chủ thể, bối cảnh, phong cách, ánh sáng, góc máy.
nintegerKhông bắt buộc: Số ảnh, từ 1 đến 10 (mặc định 1). Mỗi model có giới hạn riêng, thường là 4; vượt quá sẽ bị từ chối với lỗi 400.
sizestringKhông bắt buộc: Kích thước WIDTHxHEIGHT, ví dụ 1024x1024, 1536x1024, 1024x1536, hoặc auto. Cạnh dài nhất quyết định mức giá (xem bên dưới). Model nào không làm được kích thước đó thì tự báo lỗi.
qualitystringKhông bắt buộc: Mức chất lượng nếu model hỗ trợ, ví dụ low, medium, high.
response_formatstringKhông bắt buộc: b64_json hoặc url, nếu model hỗ trợ. Một số model luôn trả b64_json.
streambooleanKhông bắt buộc: Không hỗ trợ: gửi true sẽ bị từ chối với lỗi 422.

Kích thước, độ phân giải và giá#

Giá được tính theo từng ảnh: giá mỗi ảnh × hệ số độ phân giải × số ảnh trả về.

Với model chia mức độ phân giải, cạnh dài nhất của size chọn mức: tới 1024 px là 1K (×1), tới 2048 px là 2K (×2), lớn hơn là 4K (×4).
auto hoặc không gửi size thì dùng kích thước mặc định của model.
Model không chia mức thì mọi kích thước cùng một giá.
Chỉ tính tiền những ảnh thực sự trả về. Request lỗi không bị tính phí.

Ví dụ: model giá 100 ₫/ảnh, size là 2048x2048, n là 2 → 2 ảnh × 100 ₫ × 2 = 400 ₫.

Sửa ảnh từ ảnh có sẵn#

Gửi ảnh gốc và lời dặn tới POST /v1/images/edits dưới dạng multipart/form-data (không nhận JSON). Chỉ model có images.edits trong endpoints mới sửa ảnh được.

imagefileBắt buộc: Ảnh gốc (PNG, JPEG hoặc WebP). Tên trường phải đúng là image. Cả request tối đa 25 MB.
promptstringBắt buộc: Điều cần thay đổi, ví dụ "đổi nền thành bãi biển lúc hoàng hôn".
modelstringBắt buộc: ID model có images.edits.
maskfileKhông bắt buộc: Ảnh PNG có vùng trong suốt đánh dấu chỗ cần sửa, nếu model hỗ trợ.
nintegerKhông bắt buộc: Số ảnh, từ 1 đến 10 (mặc định 1).
sizestringKhông bắt buộc: Kích thước ảnh kết quả; cũng quyết định mức giá như khi tạo ảnh.

POST /v1/images/edits

curl https://api.xpncore.com/v1/images/edits \
  -H "Authorization: Bearer $XPNCORE_API_KEY" \
  -F model=IMAGE_MODEL_ID \
  -F [email protected] \
  -F prompt="Give the fox a red scarf and make it snow" \
  -F size=1024x1024 | jq -r '.data[0].b64_json' | base64 --decode > fox-winter.png

Lỗi thường gặp#

Lỗi trả về dạng {"error": {"code", "message", "type"}} mà SDK OpenAI đọc được. Request lỗi không bị tính phí.

400 BAD_REQUEST: n ngoài khoảng cho phép, hoặc thiếu multipart khi sửa ảnh.
400 CONTENT_POLICY_BLOCKED: prompt vi phạm chính sách nội dung; hãy viết lại.
402 INSUFFICIENT_FUNDS: số dư ví không đủ. KEY_SPEND_LIMIT: khóa đã chạm giới hạn chi tiêu bạn đặt.
403 FORBIDDEN: khóa không được dùng model này, hoặc tính năng tạo ảnh đang tắt.
422 VALIDATION_ERROR: thiếu model/prompt, model không tạo ảnh, hoặc gửi stream: true.
429 RATE_LIMITED: gửi quá nhanh; chờ rồi thử lại.
503 MODEL_PRICING_UNAVAILABLE: model chưa có giá, tạm thời chưa dùng được. SERVICE_UNAVAILABLE: model đang gián đoạn; thử lại sau ít phút.

Mẹo dùng hiệu quả#

Lưu ảnh ngay. API không giữ ảnh giúp bạn; link url (nếu có) có thể hết hạn sau một thời gian.
Thử với 1K trước, ưng bố cục rồi mới tạo lại ở 2K/4K để tiết kiệm.
Đừng tự gửi lại khi chưa rõ kết quả. Mỗi lần thành công là một lần tính phí; hãy đặt timeout ít nhất 3 phút vì ảnh lớn có thể lâu.
Prompt rõ ràng: chủ thể → hành động → bối cảnh → phong cách → ánh sáng → góc máy. Viết bằng tiếng Anh thường cho kết quả ổn định hơn.
Muốn thử nhanh không cần code, dùng Chat AI › Tạo ảnh trong bảng điều khiển.

Mở trình hướng dẫn thiết lập Playground