
Hướng dẫn Ideogram 4.6 API này đưa bạn từ API key đến một ảnh hoàn chỉnh bằng cURL và Python, rồi đi qua mọi chế độ đầu vào mà schema của PoYo chấp nhận: text-to-image với kích thước preset hoặc tùy chỉnh, nền trong suốt, chỉnh sửa thông thường, chỉnh sửa bằng mask, ảnh tham chiếu và chỉnh sửa độ chính xác cao. Text-to-image dùng model ID ideogram-v4.6 và chỉnh sửa dùng ideogram-v4.6-edit; cả hai đều có trên trang model Ideogram 4.6.
Quy tắc của các trường lấy từ tài liệu tham chiếu API của PoYo. Để biết model này là gì và so sánh ra sao, hãy bắt đầu với tổng quan Ideogram 4.6 API.
Bước 1: gửi request Ideogram 4.6 API bằng cURL
Tạo một key trong dashboard của PoYo và export nó thành POYO_API_KEY. Giữ key trên server của bạn, không đặt trong code trình duyệt.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ideogram-v4.6",
"input": {
"prompt": "A colorful storefront with a neon sign reading \"HELLO\""
}
}'
Request này dùng giá trị mặc định: size: auto (khoảng 2K), quality: medium, một ảnh, nên tốn 12 credit ($0.06). Một lần gửi thành công trả về code: 200 và một object data với task_id, status: "not_started" và created_time. Đó là một task đang chờ xử lý, chưa phải ảnh. Hãy kiểm tra code trong body mỗi lần: một số lỗi xác thực trả về HTTP 200 kèm code: 400.
Bước 2: polling trạng thái task
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Trạng thái đi qua not_started, running, rồi finished hoặc failed. Một task đã hoàn tất liệt kê mỗi ảnh một mục trong data.files, mỗi mục có file_url và file_type: "image", đồng thời báo phí đã trừ trong credits_amount. Một task thất bại giải thích lý do trong error_message.
Bước 3: vòng lặp polling Python có giới hạn thời gian
Vòng lặp này kiểm tra cả mã trạng thái HTTP lẫn code trong body, dừng khi gặp failed, trả về mọi ảnh khi n lớn hơn 1, và bỏ cuộc sau 10 phút mà không gửi lại.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
body = response.json()
if response.status_code >= 400 or body.get("code") != 200:
error = body.get("error") or {}
raise RuntimeError(f"PoYo error {body.get('code')}: {error.get('message', body)}")
return body["data"]
def run(model, input_body, max_wait=600):
task = checked(session.post(BASE + "/api/generate/submit",
json={"model": model, "input": input_body},
timeout=60))
task_id = task["task_id"]
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
images = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "image"]
return images, task.get("credits_amount")
raise TimeoutError("Still running, check this task later: " + task_id)
images, credits = run("ideogram-v4.6", {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "1728x2304",
"quality": "high",
"n": 2,
})
print(images, credits)
1728x2304 là kích thước 3:4 với 3,981,312 pixel, dưới ngưỡng 4,194,304 pixel, nên hai ảnh được tính theo mức 2K high: 2 × 20 = 40 credit ($0.20). Hết thời gian chờ nghĩa là "hãy kiểm tra lại cùng task ID đó sau". Gửi lại sẽ khởi tạo một task tính phí thứ hai. Cùng hàm run() này cũng dùng được cho chỉnh sửa: truyền "ideogram-v4.6-edit" làm model.
Mọi chế độ đầu vào của Ideogram 4.6 API
Mọi trường đều nằm trong input. Model ID và callback_url tùy chọn nằm ở cấp cao nhất.
Text-to-image ở 4K
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
"size": "2048x3072",
"quality": "high",
"n": 2
}
}
2048x3072 là 6,291,456 pixel, lớn hơn 4,194,304, nên đây là bậc 4K và very_low không được phép ở kích thước này.
Nền trong suốt và seed cố định
{
"model": "ideogram-v4.6",
"input": {
"prompt": "A flat sticker of a smiling coffee cup",
"size": "1:1 HD",
"quality": "low",
"background": "transparent",
"seed": 42
}
}
transparent trả về ảnh có kênh alpha; opaque buộc dùng nền đặc. Gửi cùng body với cùng seed để lặp lại kết quả.
Chỉnh sửa thông thường
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Replace the background with a blue photo studio",
"image_urls": [
"https://example.com/source.png"
]
}
}
Chỉnh sửa thông thường tạo lại ảnh từ prompt. image_urls phải là mảng chứa đúng một ảnh, dưới dạng URL HTTP(S) công khai hoặc data URI base64. Để gửi file cục bộ, hãy tải chúng lên trước bằng endpoint tải file của PoYo.
Đổi phong cách theo ảnh tham chiếu
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Restyle the product shot to match the reference",
"image_urls": [
"https://example.com/product.png"
],
"reference_image_urls": [
"https://example.com/style.png"
],
"size": "2048x2048",
"quality": "low",
"n": 2
}
}
Cho phép tối đa 4 ảnh tham chiếu, hoặc 3 khi có mask. size tùy chỉnh được phép ở đây vì đây là chỉnh sửa thông thường không có mask.
Chỉnh sửa độ chính xác cao trên toàn ảnh
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change only the date line to \"JULY 3-5 · RIVERSIDE PARK\". Keep everything else exactly the same.",
"image_urls": [
"https://example.com/poster.png"
],
"edit_precision": "high",
"context_window": "none",
"size": "auto",
"quality": "high"
}
}
Đây là body của lần chỉnh sửa trong ngày ra mắt của chúng tôi (task 672JRU198S22NS8D, ngày 20 tháng 11 năm 2026), chỉ thay URL nguồn. Ảnh nguồn là một poster 2304×3072; ảnh đầu ra giữ nguyên kích thước đó và chỉ thay đổi dòng ngày, và task bị tính 120 credit ($0.60), mức chỉnh sửa 4K high.
Chỉnh sửa cục bộ bằng mask
{
"model": "ideogram-v4.6-edit",
"input": {
"prompt": "Change the sign text to \"OPEN LATE\"",
"image_urls": [
"https://example.com/storefront.png"
],
"mask_url": "https://example.com/sign-mask.png",
"edit_precision": "high",
"context_window": "auto",
"quality": "high"
}
}
Mask phải khớp kích thước ảnh nguồn và chứa cả vùng đen (chỉnh sửa) lẫn vùng trắng (giữ nguyên). Với context_window: auto, chỉ vùng quanh mask được chỉnh sửa ở độ phân giải nguồn. Mask quá lớn sẽ quay về chỉnh sửa toàn ảnh.
Quy tắc xác thực các trường
Hãy xác thực ở phía bạn trước khi gửi để các request sai thất bại sớm:
| Trường | Quy tắc |
|---|---|
model | ideogram-v4.6 hoặc ideogram-v4.6-edit |
prompt | Bắt buộc, 1 đến 10,000 ký tự, không chỉ có khoảng trắng |
size | auto, 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16 hoặc WIDTHxHEIGHT với chữ x viết thường |
| Kích thước tùy chỉnh | Mỗi cạnh từ 256 đến 4096 và là bội số của 32; tỷ lệ khung hình trong khoảng 1:6 đến 6:1 |
quality | very_low chỉ khi ảnh đầu ra tối đa 4,194,304 pixel |
n | Số nguyên 1 đến 8; chuỗi và boolean bị từ chối |
image_urls | Chỉ cho chỉnh sửa; mảng chứa đúng một ảnh |
mask_url, edit_precision: high | Cần size: auto (hoặc không có size) |
background | Bị từ chối khi edit_precision là high |
context_window: auto | Cần mask_url và edit_precision: high |
| Trường không xác định | Bị từ chối với lỗi unsupported fields |
Ví dụ: 2304x3072 hợp lệ (cả hai cạnh là bội số của 32); 1296x3168 thất bại vì 1296 không phải bội số của 32, dù Ideogram 4.5 từng chấp nhận nó; 4096x512 thất bại (tỷ lệ 8:1); very_low ở 2048x3072 thất bại.
Các lỗi nên xử lý
code | Ý nghĩa | Cần làm gì |
|---|---|---|
| 400 | Tham số không hợp lệ | Sửa body; không thử lại nguyên trạng |
| 401 | Thiếu API key hoặc API key không hợp lệ | Kiểm tra header Authorization: Bearer |
| 402 | Không đủ credit | Nạp thêm, rồi gửi lại |
| 429 | Vượt giới hạn tốc độ | Lùi lại và thử lại sau |
| 500, 502, 503 | Lỗi server, upstream hoặc khả dụng | Thử lại với backoff; trước tiên kiểm tra xem đã có task ID được trả về chưa |
Một task chuyển sang failed có lý do trong error_message. Xem Mã lỗi để biết danh sách đầy đủ.
Dùng callback thay cho polling
Thêm "callback_url": "https://your-app.example.com/poyo-webhook" ở cấp cao nhất của body, không đặt trong input. Khi task hoàn tất hoặc thất bại, PoYo POST dữ liệu task tới URL đó, được ký bằng HMAC-SHA256 trong header X-Webhook-Signature; tài liệu webhook nêu quy tắc chữ ký. Hãy giữ một cơ chế polling chậm làm dự phòng cho các callback không bao giờ đến.
Hóa đơn đầu tiên của bạn được tính thế nào
Ideogram 4.6 API tính phí theo mỗi ảnh đầu ra: giá của bậc chất lượng và kích thước × n. 1 credit = $0.005.
| Request | Bậc | Phí |
|---|---|---|
Mặc định (auto, medium, n: 1) | Text-to-image medium 2K | 12 credit ($0.06) |
very_low, 3:4, n: 1 | Text-to-image very_low 2K | 1.6 credit ($0.008) |
high, 1728x2304, n: 2 | Text-to-image high 2K | 40 credit ($0.20) |
high, 2304x3072, n: 1 | Text-to-image high 4K | 40 credit ($0.20) |
Chỉnh sửa độ chính xác cao trên ảnh nguồn 2304×3072, high | Chỉnh sửa high 4K | 120 credit ($0.60) |
Các dòng very_low và 2304x3072 khớp với phí thực tế của các task trong ngày ra mắt của chúng tôi. Với chỉnh sửa dùng size: auto, giá được báo theo kích thước ảnh nguồn và quyết toán theo ảnh được giao, không bao giờ cao hơn giá báo. Bài viết về giá có thêm nhiều ví dụ tính toán.
Câu hỏi thường gặp
Ideogram 4.6 API có tương thích với OpenAI SDK không?
Không. Đây là API tác vụ bất đồng bộ: gửi tới /api/generate/submit, rồi polling /api/generate/status/{task_id} hoặc nhận callback. Dùng requests, fetch hoặc cURL thông thường đều được.
Làm thế nào để chỉnh sửa ảnh bằng Ideogram 4.6 API?
Gọi ideogram-v4.6-edit với một URL trong image_urls và nội dung thay đổi trong prompt. Thêm edit_precision: high để giữ các pixel bạn không yêu cầu thay đổi.
Tôi có thể gửi ảnh tham chiếu tới ideogram-v4.6 không?
Không. Trên PoYo, ảnh tham chiếu đặt trong reference_image_urls của ideogram-v4.6-edit, tối đa 4, hoặc 3 khi có mask.
Một request Ideogram 4.6 API trả về bao nhiêu ảnh?
1 đến 8, thiết lập bằng n. Mỗi ảnh được tính theo giá của bậc.
Vì sao request Ideogram 4.6 API của tôi bị từ chối vì kích thước?
Các cạnh tùy chỉnh phải là bội số của 32 trong khoảng 256 đến 4096, và mask hoặc chỉnh sửa độ chính xác cao cần size: auto.