Tạo ảnh

Tạo ảnh mới từ mô tả bằng chữ.

Đã triển khaiKhả dụng hay không còn phụ thuộc model bạn chọn đã được bật và có giá trong ApiLux.

Request

POST/images/generations

Cần header Authorization: Bearer apl_...

Field	Kiểu	Mô tả
`model`bắt buộc	string	Public model ID có `kind` là `IMAGE`.
`prompt`bắt buộc	string	Mô tả ảnh cần tạo. Tối đa 4000 ký tự.
`size`	string	Ví dụ `"1024x1024"`. Chỉ có tác dụng với model hỗ trợ.
`n`	integer	Số ảnh muốn tạo, 1–4. Mặc định 1.

Response

Field	Kiểu	Mô tả
`data[].b64_json`bắt buộc	string	Ảnh dạng base64. ApiLux luôn trả base64, không trả URL của nhà cung cấp.
`data[].mime_type`bắt buộc	string	Ví dụ `image/png`.
`usage.images`bắt buộc	integer	Số ảnh đã tính phí.
`apilux.credit_charged`bắt buộc	integer	Số credit đã trừ.

Tính tiền

Theo số ảnh thực tế được tạo, không theo n bạn yêu cầu — một số model chỉ trả 1 ảnh dù xin nhiều hơn.

Ví dụ

cURL

curl https://apilux.net/api/v1/images/generations \
  -H "Authorization: Bearer apl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 360 \
  -d '{
    "model": "IMAGE_MODEL_ID",
    "prompt": "Giao diện SaaS sáng, tối giản",
    "size": "1024x1024"
  }' \
  | jq -r '.data[0].b64_json' | base64 -d > image.png

Node.js

import { writeFileSync } from "node:fs";

const res = await fetch("https://apilux.net/api/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APILUX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "IMAGE_MODEL_ID",
    prompt: "Giao diện SaaS sáng, tối giản",
  }),
});
const data = await res.json();
writeFileSync("image.png", Buffer.from(data.data[0].b64_json, "base64"));

Python

import base64, os, requests

res = requests.post(
    "https://apilux.net/api/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['APILUX_API_KEY']}"},
    json={"model": "IMAGE_MODEL_ID", "prompt": "Giao diện SaaS sáng, tối giản"},
    timeout=360,
)
with open("image.png", "wb") as f:
    f.write(base64.b64decode(res.json()["data"][0]["b64_json"]))

Lỗi

HTTP	Mã	Ý nghĩa
400	`invalid_request`	Body không hợp lệ (thiếu field, sai kiểu, giá trị ngoài phạm vi).
401	`auth_missing_or_malformed`	Thiếu header `Authorization` hoặc sai định dạng. Phải là `Bearer apl_...`.
401	`auth_invalid`	API key không tồn tại.
401	`auth_revoked`	API key đã bị thu hồi.
401	`auth_expired`	API key đã hết hạn.
400	`unknown_model`	Model không tồn tại trong ApiLux.
400	`capability_not_supported`	Model có tồn tại nhưng không dùng được ở endpoint này (ví dụ dùng model text cho endpoint ảnh).
503	`pricing_not_configured`	Model đã có route nhưng chưa được cấu hình giá trong ApiLux. Đây là trạng thái phía chúng tôi, không phải lỗi của bạn.
503	`model_disabled`	Model đang bị tắt.
503	`model_temporarily_unavailable`	Model đang bật và có giá, nhưng nhà cung cấp phía sau hiện không phục vụ nó. Đây là trạng thái tạm thời và có thể tự hết — model sẽ xuất hiện lại trong `GET /v1/models` khi nhà cung cấp có nó trở lại. Bạn không bị trừ tiền và không có lời gọi nào tới nhà cung cấp.
402	`insufficient_balance`	Số dư ví không đủ để thực hiện request.
409	`duplicate_request`	Đã có một request TẠO với cùng `Idempotency-Key` đang chạy hoặc đã hoàn tất. ApiLux KHÔNG gọi nhà cung cấp lần hai và KHÔNG trừ tiền lần hai. Nếu request gốc đã xong, response kèm `job_id` để bạn lấy kết quả ở đó. Chỉ áp cho các endpoint tạo media (`images/generations`, `images/edits`, `videos/generations`).
429	`api_key_limit_exceeded`	API key này đã chạm hạn mức bạn tự cấu hình. Ví vẫn còn tiền — chỉ key này không được tiêu thêm cho tới khi chu kỳ reset. Response kèm `limit_type` (`spending` \| `requests` \| `tokens`) và `period` (`daily` \| `monthly` \| `lifetime`). Hạn mức token của endpoint text được tính theo usage thực tế nên tổng có thể vượt tối đa một request.
503	`api_key_quota_reconciliation_required`	Một request text trước đó của chính key này chưa được đối soát xong. Thường gặp nhất: nhà cung cấp trả kết quả thành công nhưng không kèm usage token, nên hạn mức token của kỳ đó không còn đáng tin và ApiLux dừng lại thay vì để hạn mức bị vượt trong im lặng. Thử lại sẽ không qua được cho tới khi việc đó xong — hãy liên hệ hỗ trợ. Bạn không bị trừ tiền cho request bị chặn, không có lời gọi nào tới nhà cung cấp, và endpoint ảnh/video không bị ảnh hưởng.
429	`rate_limit_exceeded`	Vượt hạn mức tốc độ (request mỗi giây hoặc mỗi phút). Kèm header `Retry-After` và trường `retry_after_seconds`; `limit_type` cho biết trục nào chặn. Request bị chặn KHÔNG gọi nhà cung cấp và KHÔNG bị trừ tiền. Chờ đúng số giây rồi thử lại.
503	`system_maintenance`	ApiLux đang bảo trì. Toàn bộ endpoint sinh nội dung tạm dừng; bạn không bị trừ tiền và không có lời gọi nào tới nhà cung cấp. Thử lại sau.
503	`ai_requests_disabled`	Người vận hành đã tạm ngừng nhận request AI, trong khi phần còn lại của dịch vụ vẫn chạy. Tách khỏi `system_maintenance` vì đây là công tắc hẹp hơn.
503	`provider_catalog_stale`	ApiLux không còn bằng chứng đủ mới về việc nhà cung cấp còn phục vụ model nào, nên dừng lại thay vì tính tiền một request có thể hỏng. Đây là sự cố phía chúng tôi, không phải model bị gỡ — nó tự hết ngay khi một lần đồng bộ thành công quay lại. Thử lại sau vài phút là hợp lý.
502	`upstream_error`	Nhà cung cấp mô hình lỗi. Không bị trừ tiền.
504	`upstream_timeout`	Nhà cung cấp không phản hồi kịp. Không bị trừ tiền.
429	`upstream_rate_limited`	Bị giới hạn tốc độ. Thử lại sau vài giây.

Ghi chú

Tạo ảnh chậm hơn chat đáng kể. Đặt timeout client từ 180 đến 360 giây.