Tạo hình ảnh

Biến mô tả văn bản (prompt) thành hình ảnh bằng các model hình ảnh của Google (dòng Nano Banana / Gemini Image). Endpoint tương thích OpenAI Images API — chỉ cần trỏ SDK openai tới base URL của Geraikita, dùng cùng gk- key và cùng số dư GeraiPoints.

Endpoint

POSThttps://ai.geraikita.com/v1/images/generations

Header	Giá trị
Authorization	Bearer gk-... (hoặc x-api-key: gk-...)
Content-Type	application/json

Một yêu cầu = một prompt, cho ra 1–4 ảnh. Không hỗ trợ streaming — phản hồi được gửi một lần khi ảnh đã xong.

Tham số body

Tham số	Kiểu	Mô tả
`model`	stringbắt buộc	ID model hình ảnh, ví dụ `gemini-3.1-flash-image` hoặc `gemini-3-pro-image` — danh sách đầy đủ ở bảng giá bên dưới.
`prompt`	stringbắt buộc	Mô tả ảnh bạn muốn, tối đa 4000 ký tự.
`n`	integertùy chọn	Số lượng ảnh, `1`–`4`. Mặc định `1`. Mỗi ảnh thành công được tính phí riêng.
`size`	stringtùy chọn	Một trong `auto \| 1024x1024 \| 1536x1024 \| 1024x1536 \| 1792x1024 \| 1024x1792`. Mặc định `auto`: model tự chọn tỉ lệ, thường là ngang 16:9 (khoảng 1376×768). Kích thước chỉ là gợi ý tỉ lệ — độ phân giải cuối cùng do model quyết định.
`response_format`	stringtùy chọn	`url` (mặc định) để nhận liên kết ảnh, hoặc `b64_json` để nhận dữ liệu ảnh base64 ngay trong phản hồi.

Các trường khác (ví dụ quality hoặc style) sẽ bị bỏ qua.

Ví dụ

Thời gian xử lý thường là 15–45 giây mỗi yêu cầu, và có thể lên tới khoảng 4 phút khi dùng tuyến dự phòng. Đặt timeout phía client tối thiểu 300 giây để yêu cầu không bị ngắt trước khi ảnh xong.

bash

curl https://ai.geraikita.com/v1/images/generations \
  --max-time 300 \
  -H "Authorization: Bearer gk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "Poster quảng cáo cà phê sữa đá đường thốt nốt trên bàn gỗ, ánh nắng sớm ấm áp, dòng chữ lớn \"GIẢM 20%\" ở phía trên, phong cách minh họa phẳng",
    "n": 1,
    "size": "1024x1024"
  }'

Ví dụ phản hồi

data chứa một đối tượng cho mỗi ảnh thành công — url hoặc b64_json tùy theo response_format. Nếu một số ảnh thất bại, số đối tượng có thể ít hơn n.

200 OK · application/json

{
  "created": 1793464057,
  "data": [
    { "url": "https://api.geraikita.com/cdn/ai-gambar/2026/11/xxxxxxxxxxxx.jpg" }
  ]
}

Header phản hồi: X-Geraikita-Images = số ảnh thành công, X-Geraikita-GP-Charged = số GeraiPoints bị trừ cho yêu cầu đó.

Giá

Model hình ảnh được tính phí theo mỗi ảnh tạo thành công — không theo token. Giá hiện tại (có thể thay đổi) có trong bảng dưới đây và trên trang giá.

Hiện không tải được giá model hình ảnh — xem trang giá.

Ảnh thất bại không bị tính phí, các yêu cầu bị từ chối (tham số sai hoặc vi phạm chính sách nội dung) cũng vậy.
Số dư GeraiPoints phải đủ cho n × giá mỗi ảnh trước khi yêu cầu được xử lý; nếu không, phản hồi là 402.
Model hình ảnh không nằm trong Unlimited plan, Bansos (gói miễn phí) hay bất kỳ hạn mức miễn phí nào khác — luôn trừ vào số dư GeraiPoints.
Mỗi ảnh được ghi thành một dòng trong lịch sử sử dụng ở dashboard, có nhãn Ảnh.

Mã lỗi

Lỗi theo định dạng OpenAI: đối tượng error gồm message, type, param và code.

Mã	type / code	Ý nghĩa
400	`invalid_request_error`	Tham số không hợp lệ (ví dụ `n` ngoài 1–4, `size` không xác định, prompt trống hoặc quá dài). Không tính phí.
400	`content_policy_violation`	Prompt vi phạm chính sách nội dung (xem bên dưới). Không tính phí.
401	`—`	Thiếu API key hoặc key không hợp lệ.
402	`insufficient_quota`	Không đủ GeraiPoints cho số ảnh yêu cầu — vui lòng nạp thêm.
403	`—`	Model này không được phép với API key đó — hãy thêm vào danh sách model của key trong dashboard.
404	`model_not_found`	Model không xác định hoặc không phải model hình ảnh.
429	`rate_limit_exceeded`	Quá nhiều yêu cầu — giới hạn là 10 yêu cầu/phút mỗi key. Hãy chờ theo header `Retry-After`.
502	`image_generation_failed`	Tạo ảnh thất bại phía máy chủ. Không tính phí — vui lòng thử lại.

Ví dụ lỗi

{
  "error": {
    "message": "...",
    "type": "...",
    "param": "...",
    "code": "..."
  }
}

Gọi model hình ảnh qua /v1/chat/completions sẽ nhận 400 kèm chỉ dẫn tới endpoint này — hãy dùng /v1/images/generations.

Mẹo viết prompt

Có thể viết prompt bằng tiếng Việt, tiếng Anh, tiếng Indonesia hoặc ngôn ngữ khác.
Model có thể viết chữ trong ảnh — đặt đúng nội dung chữ trong dấu ngoặc kép, ví dụ dòng chữ "GIẢM 20%".
Mô tả chủ thể, bối cảnh, phong cách (ảnh chụp, minh họa phẳng, 3D, màu nước), ánh sáng và bố cục — càng cụ thể, kết quả càng sát ý.
Chọn size theo mục đích: 1024x1024 cho feed, 1024x1792 cho story/dọc, 1792x1024 cho banner ngang.
Cần nhiều biến thể? Dùng n tối đa 4 trong một yêu cầu — nhớ rằng mỗi ảnh thành công đều bị tính phí.

Chính sách nội dung

Các yêu cầu sau sẽ bị từ chối:

Nội dung tình dục hoặc khiêu dâm.
Nội dung bóc lột hoặc gây nguy hiểm cho trẻ em.
Bạo lực tàn ác hoặc máu me (gore).
Nhân vật chính trị có thật hoặc người của công chúng có thật.

Yêu cầu bị từ chối trả về 400 với mã content_policy_violation và không bị tính phí.

Liên kết ảnh & lưu trữ

URL trong data[].url là công khai — ai có liên kết đều mở được ảnh — và không được đảm bảo tồn tại mãi mãi. Hãy tải về và lưu bản sao vào kho lưu trữ của bạn ngay sau khi tạo, hoặc yêu cầu b64_json để nhận dữ liệu ảnh trực tiếp trong phản hồi.

Tạo hình ảnh

Endpoint#

Tham số body#

Ví dụ#

Ví dụ phản hồi#

Giá#

Mã lỗi#

Mẹo viết prompt#

Chính sách nội dung#

Liên kết ảnh & lưu trữ#