🖼️ Image Generation API
Hướng dẫn chi tiết cách sử dụng Beeknoee Image Generation API để tạo ảnh từ text và chỉnh sửa ảnh (editing). Hỗ trợ 5 nhà cung cấp: OpenAI (7 models), Google (7 models), Black Forest Labs (2 Flux 2), Alibaba (2 Wan 2.7), xAI (2 Grok Imagine).
3 endpoints chính:
| Endpoint | Chức năng | Body |
|---|---|---|
POST /v1/image/generations | Tạo ảnh từ text | JSON |
POST /v1/image/edits | Chỉnh sửa ảnh có sẵn | multipart/form-data |
Không cần viết code: có thể tạo ảnh ngay trong AI Studio trên Dashboard. Video hướng dẫn:
Endpoint
POST https://platform.beeknoee.com/v1/image/generations
💡 Alias chuẩn OpenAI:
/api/v1/images/generations(số nhiều) cũng hoạt động — tương thích trực tiếp với OpenAI SDK (client.images.generate(...)khi trỏbase_urlvề Beeknoee). Áp dụng cho cả/images/editsvàGET /images/generations/{id}.
Headers:
Authorization: Bearer sk-bee-xxxxxx
Content-Type: application/json
Danh sách Models
⭐ Một model — hai nhà cung cấp (openai/ vs bee/)
Một số model ảnh xuất hiện 2 lần trên trang Models với Model ID khác nhau — phần prefix trước dấu / là phiên bản dịch vụ:
openai/gpt-image-2→ bản tính theo token, tạo được nhiều ảnh mỗi requestbee/gpt-image-2→ bản giá cố định mỗi ảnh của Beeknoee
Cùng một model AI, cùng chất lượng ảnh — nhưng cách tính tiền và tính năng khác nhau. Khi gọi API, dùng đúng chuỗi ID trên card model (bấm nút copy ID trên card).
So sánh chi tiết: GPT Image 2
openai/gpt-image-2 | bee/gpt-image-2 | |
|---|---|---|
| Cách tính tiền | Theo token: Text In $5/1M · Image In $8/1M · Output $30/1M — chi phí thay đổi theo độ dài prompt và chất lượng ảnh | Giá cố định mỗi ảnh theo quality × resolution: 1K $0.050–0.270 · 2K $0.060–0.540 · 4K $0.070–0.800 — biết trước chi phí |
Số ảnh mỗi request (n) | Tối đa 4 | Chỉ n=1 |
💡 Chọn bản nào? Cần chi phí cố định, đoán trước được mỗi ảnh → dùng
bee/gpt-image-2. Cần n>1 ảnh mỗi request → dùngopenai/gpt-image-2.
GPT Image 1.5 bản Beeknoee (bee/gpt-image-1.5)
| Chi tiết | |
|---|---|
| Giá cố định/ảnh | Medium $0.034 · High $0.133 (1024×1024) |
| Quality | Chỉ medium / high (không có low/auto) |
| Sizes | 1024x1024, 1024x1536, 1536x1024, auto |
n | Chỉ n=1 |
| Image-to-Image | Qua image_urls trong POST /v1/image/generations (tối đa 16 ảnh input) — không dùng /v1/image/edits |
Model có hai nhà cung cấp
Cùng một model AI, nhưng ID khác nhau và cách tính tiền khác nhau. Gọi API phải dùng đúng chuỗi ID dưới đây.
| Model | Qua Beeknoee | Đi thẳng nhà cung cấp | Giá qua Beeknoee | Giá đi thẳng |
|---|---|---|---|---|
| GPT Image 1.5 | bee/gpt-image-1.5 | openai/gpt-image-1.5 | Medium 935đ ($0.034) · High 3.658đ ($0.133) | Text In 137.500đ ($5.00) /1M tokens · Image In 220.000đ ($8.00) /1M tokens · Output 880.000đ ($32.00) /1M tokens |
| GPT Image 2 | bee/gpt-image-2 | openai/gpt-image-2 | Text In 137.500đ ($5.00) /1M tokens · Image In 220.000đ ($8.00) /1M tokens · Output 825.000đ ($30.00) /1M tokens | Text In 137.500đ ($5.00) /1M tokens · Image In 220.000đ ($8.00) /1M tokens · Output 825.000đ ($30.00) /1M tokens |
Model chỉ có một bản
| Model | Model ID | Nhà cung cấp | Hãng | Giá |
|---|---|---|---|---|
| Flux 2 Flex | flux-2-flex | Beeknoee | Black Forest Labs | 1K 3.850đ ($0.14) · 2K 6.600đ ($0.24) |
| Flux 2 Pro | flux-2-pro | Beeknoee | Black Forest Labs | 1K 1.375đ ($0.05) · 2K 1.925đ ($0.07) |
| Gemini 2.5 Flash Image | gemini-2.5-flash-image | Beeknoee | 1K 1.073đ ($0.039) · 2K 1.595đ ($0.058) · 4K 2.393đ ($0.087) | |
| GPT Image 1 Mini | gpt-image-1-mini | Beeknoee | OpenAI | Low 138đ ($0.005) · Medium 413đ ($0.015) · High 990đ ($0.036) |
| Grok Imagine | grok-imagine | Beeknoee | xAI | T2I 688đ ($0.025) · I2I 825đ ($0.03) |
| Grok Imagine Quality | grok-imagine-quality | Beeknoee | xAI | Quality 1.375đ ($0.05) |
| Seedream 4.5 | seedream-4.5 | Beeknoee | ByteDance | Basic (2K) 1.375đ ($0.05) · High (4K) 2.200đ ($0.08) |
| Seedream 5.0 Lite | seedream-5-lite | Beeknoee | ByteDance | Basic (2K) 1.238đ ($0.045) · High (4K) 1.870đ ($0.068) |
| Wan 2.7 Image | wan-2.7-image | Beeknoee | Alibaba | 1K/2K 825đ ($0.03) |
| Wan 2.7 Image Pro | wan-2.7-image-pro | Beeknoee | Alibaba | 1K~4K 2.063đ ($0.075) |
| ChatGPT Image Latest | bee/chatgpt-image-latest | OpenAI | OpenAI | Low 275đ ($0.01) · Medium 1.100đ ($0.04) · High 4.675đ ($0.17) |
| gpt-image-1 | openai/gpt-image-1 | OpenAI | OpenAI | Text In 137.500đ ($5.00) /1M tokens · Image In 275.000đ ($10.00) /1M tokens · Output 1.100.000đ ($40.00) /1M tokens |
| FLUX.2 Klein 4B | black-forest-labs/flux.2-klein-4b | — | Black Forest Labs | Standard 635đ ($0.023) |
| FLUX.2 Max | black-forest-labs/flux.2-max | — | Black Forest Labs | Standard 3.190đ ($0.116) |
| FLUX.3 Image | black-forest-labs/flux-3-image | — | Black Forest Labs | 768 1.691đ ($0.061) · 1K 1.980đ ($0.072) · 1.5K 2.888đ ($0.105) · 2K 4.125đ ($0.15) · 4K 25.053đ ($0.911) |
| GPT Image 2.5 Flare | openai/gpt-image-2.5-flare | — | OpenAI | Text In 330.000đ ($12.00) /1M tokens · Image In 330.000đ ($12.00) /1M tokens · Output 1.237.500đ ($45.00) /1M tokens |
| GPT Image 2.5 Sunburst | openai/gpt-image-2.5-sunburst | — | OpenAI | Text In 330.000đ ($12.00) /1M tokens · Image In 330.000đ ($12.00) /1M tokens · Output 1.237.500đ ($45.00) /1M tokens |
| Grok Imagine Image 2.0 | x-ai/grok-imagine-image-2.0 | — | xAI | Low 1K 1.650đ ($0.06) · Low 2K 2.475đ ($0.09) · Medium 1K 2.475đ ($0.09) · Medium 2K 3.300đ ($0.12) |
| Hy Image 3.5 Preview | tencent/hy-image-v3.5-preview | — | Tencent | Output 66.000đ ($2.40) /1M tokens |
| MAI-Image-2.5 Pro | microsoft/mai-image-2.5-pro | — | Microsoft | Text In 206.250đ ($7.50) /1M tokens · Image In 330.000đ ($12.00) /1M tokens · Output 4.455.000đ ($162.00) /1M tokens |
| MAI-Image-2.6 | microsoft/mai-image-2.6 | — | Microsoft | Text In 206.250đ ($7.50) /1M tokens · Image In 330.000đ ($12.00) /1M tokens · Output 1.567.500đ ($57.00) /1M tokens |
| MAI-Image-2.6 Flash | microsoft/mai-image-2.6-flash | — | Microsoft | Text In 72.325đ ($2.63) /1M tokens · Image In 103.125đ ($3.75) /1M tokens · Output 783.750đ ($28.50) /1M tokens |
| Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image) | google/gemini-3.1-flash-lite-image | — | Text In 10.313đ ($0.375) /1M tokens · Image In 10.313đ ($0.375) /1M tokens · Output 1.237.500đ ($45.00) /1M tokens | |
| Nano Banana 2.1 | google/gemini-nano-banana-2.1 | — | Text In 61.875đ ($2.25) /1M tokens · Image In 61.875đ ($2.25) /1M tokens · Output 1.237.500đ ($45.00) /1M tokens | |
| Qwen Image 3 | qwen/qwen-image-3 | — | Qwen | 1K 1.238đ ($0.045) · 2K 1.238đ ($0.045) |
| Qwen Image 3 Pro | qwen/qwen-image-3-pro | — | Qwen | 1K 1.650đ ($0.06) · 2K 3.108đ ($0.113) |
| Recraft V4 Styles | recraft/recraft-v4-styles | — | Recraft | Standard 1.444đ ($0.052) |
| Recraft V4 Styles Pro | recraft/recraft-v4-styles-pro | — | Recraft | Standard 4.125đ ($0.15) |
| Recraft V4 Styles Pro Vector | recraft/recraft-v4-styles-pro-vector | — | Recraft | Standard 4.950đ ($0.18) |
| Recraft V4 Styles Vector | recraft/recraft-v4-styles-vector | — | Recraft | Standard 2.063đ ($0.075) |
| Recraft V4.1 | recraft/recraft-v4.1 | — | Recraft | Standard 1.444đ ($0.052) |
| Recraft V4.1 Flash | recraft/recraft-v4.1-flash | — | Recraft | Standard 289đ ($0.011) |
| Recraft V4.1 Pro | recraft/recraft-v4.1-pro | — | Recraft | Standard 8.663đ ($0.315) |
| Recraft V4.1 Pro Vector | recraft/recraft-v4.1-pro-vector | — | Recraft | Standard 12.375đ ($0.45) |
| Recraft V4.1 Utility | recraft/recraft-v4.1-utility | — | Recraft | Standard 1.444đ ($0.052) |
| Recraft V4.1 Utility Pro | recraft/recraft-v4.1-utility-pro | — | Recraft | Standard 8.663đ ($0.315) |
| Recraft V4.1 Vector | recraft/recraft-v4.1-vector | — | Recraft | Standard 3.300đ ($0.12) |
| Riverflow V2.5 Fast | sourceful/riverflow-v2.5-fast | — | Sourceful | 1K 784đ ($0.029) · 2K 866đ ($0.032) |
| Riverflow V2.5 Pro | sourceful/riverflow-v2.5-pro | — | Sourceful | 1K 5.363đ ($0.195) · 2K 6.188đ ($0.225) · 4K 7.013đ ($0.255) |
| Seedream 5.0 Flash | bytedance-seed/seedream-5-0-flash | — | ByteDance | 1K 743đ ($0.027) · 2K 743đ ($0.027) |
| Seedream 5.0 Pro | bytedance-seed/seedream-5-0-pro | — | ByteDance | 1K 1.856đ ($0.068) · 2K 3.713đ ($0.135) |
\uD83D\uDD04 Bảng trên lấy trực tiếp từ hệ thống, tự cập nhật khi danh mục model thay đổi. Giá tính bằng VND; số trong ngoặc là quy đổi tham khảo theo tỷ giá 1 USD = 27.500đ. Xem đầy đủ kèm rate limit tại trang Models.
ℹ️ ID chính xác để gọi API là chuỗi trong cột Model ID ở bảng trên. Nhiều model không có prefix (
dall-e-3), một số có (bee/gpt-image-2,openai/gpt-image-1) — không có quy tắc đoán được, cứ chiếu đúng bảng.
🆕 Nhóm model ảnh mới — tham số theo từng model
Các model ảnh mới (Recraft, Riverflow, Qwen Image 3, FLUX.3 / FLUX.2 Max / Klein, Seedream 5.0 Flash / Pro, Grok Imagine Image 2.0, MAI Image, GPT Image 2.5, Nano Banana 2.1, Hunyuan Image…) gọi cùng endpoint POST /v1/image/generations, nhưng dùng bộ tham số chung sau thay cho size cố định:
| Tham số | Ý nghĩa |
|---|---|
aspect_ratio | Tỉ lệ khung: 1:1, 16:9, 9:16, 4:3, 3:2… (mỗi model một danh sách). Không gửi thì lấy từ size (vd 1536x1024 ⇒ 3:2), mặc định 1:1 |
resolution | Độ phân giải 512 / 768 / 1K / 1.5K / 2K / 4K — chỉ model có tham số này; giá đổi theo độ phân giải |
quality | Chỉ model có mức chất lượng (vd Grok Imagine Image 2.0: low / medium; GPT Image 2.5: low / medium / high / auto) |
n | Số ảnh mỗi lượt — tối đa theo từng model |
image_urls | Ảnh tham chiếu (URL https:// hoặc data URI) — số ảnh tối đa theo từng model. Recraft V4 Styles bắt buộc ≥ 1 ảnh phong cách |
output_format / background | Chỉ model hỗ trợ (vd Riverflow: nền trong suốt). Recraft Vector trả ảnh SVG |
Xem năng lực + giá của từng model: GET /models/image → trường media_pricing (caps: các giá trị được phép; prices: giá USD theo chất lượng|độ phân giải, * = model không có tham số đó). Giá ở bảng trên và trên trang Models đã lấy từ đây.
Cách tính phí: giá theo biến thể (độ phân giải / chất lượng) × số ảnh thật nhận được (+ phí ảnh tham chiếu ở vài model). Riêng GPT Image 2.5, MAI Image, Nano Banana 2.1, Hunyuan Image tính theo token (giá /1M token như GPT Image). Tham số ngoài danh sách được phép ⇒ báo lỗi 400 ngay, không trừ tiền.
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" -H "Content-Type: application/json" \
-d '{"model": "qwen/qwen-image-3-pro", "prompt": "A cozy coffee shop, watercolor", "resolution": "2K", "aspect_ratio": "16:9"}'
Cấu hình cho OpenAI Models
Parameters
| Tham số | Bắt buộc | Mặc định | Áp dụng cho | Mô tả |
|---|---|---|---|---|
model | ✅ | — | Tất cả | Tên model — dùng đúng ID trên card (VD: openai/gpt-image-1.5, bee/gpt-image-2) |
prompt | ✅ | — | Tất cả | Mô tả ảnh cần tạo. Càng chi tiết càng tốt |
size | ❌ | 1024x1024 | Tất cả | Kích thước/khung hình ảnh — xem Sizes hỗ trợ theo model |
quality | ❌ | auto | GPT Image | low, medium, high, auto (auto ≈ medium). DALL-E 3: standard/hd |
resolution | ❌ | 1K | chỉ gpt-image-2 | Độ phân giải 1K/2K/4K — tách khỏi size (khung hình). 2K/4K nét hơn nhưng đắt hơn. Xem bảng giá |
n | ❌ | 1 | DALL-E 2, GPT Image | Số ảnh tạo. Hầu hết = 1; DALL-E 2 tối đa 10. bee/gpt-image-2 chỉ n=1 |
style | ❌ | vivid | chỉ DALL-E 3 | vivid hoặc natural |
background | ❌ | auto | GPT Image (gpt-image-1/1.5/2) | Nền ảnh: auto, transparent (tách nền sẵn), opaque |
output_format | ❌ | png | gpt-image-2 | Định dạng file: png, jpeg, webp |
image_urls | ❌ | — | model hỗ trợ i2i | Mảng ảnh đầu vào để sửa ảnh (image-to-image). Xem Image-to-Image |
Sizes hỗ trợ
| Model | Sizes |
|---|---|
gpt-image-1 / gpt-image-1.5 / gpt-image-1-mini / chatgpt-image-latest | 1024x1024, 1024x1536, 1536x1024, auto |
gpt-image-2 (bee/gpt-image-2) — 8 khung hình | 1024x1024 (1:1), 1792x1024 (16:9), 1024x1792 (9:16), 1024x768 (4:3), 768x1024 (3:4), 1792x768 (21:9), 1536x1024 (3:2), 1024x1536 (2:3), auto |
dall-e-3 | 1024x1024, 1024x1792, 1792x1024, 1024x1536, 1536x1024 |
dall-e-2 | 256x256, 512x512, 1024x1024, 1024x1536, 1536x1024 |
🖼️
gpt-image-2hỗ trợ 8 khung hình (1:1, 16:9, 9:16, 4:3, 3:4, 21:9, 3:2, 2:3) — nhiều nhất trong các model ảnh. Độ phân giải chọn qua tham sốresolutionriêng (1K/2K/4K); giá chỉ đổi theo quality × resolution, KHÔNG đổi theo khung hình.
Ví dụ đầy đủ tham số: bee/gpt-image-2
curl -X POST https://platform.beeknoee.com/api/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "bee/gpt-image-2",
"prompt": "A cinematic wide shot of a mountain lake at sunrise, mist over water",
"size": "1792x1024",
"resolution": "2K",
"quality": "high"
}'
3 tham số độc lập của gpt-image-2 — hiểu rõ để không nhầm:
| Tham số | Chọn gì | Ảnh hưởng giá? |
|---|---|---|
size | Khung hình (tỉ lệ): 1792x1024=16:9, 1024x1792=9:16, 1792x768=21:9… | ❌ Không |
resolution | Độ phân giải (độ nét/lớn): 1K / 2K / 4K | ✅ Có |
quality | Chất lượng render: low / medium / high (auto≈medium) | ✅ Có |
Ví dụ trên: ảnh 16:9, độ nét 2K, chất lượng high → giá =
High × 2K = $0.540/ảnh. Đổi khung hình sang 21:9 (size: "1792x768") không đổi giá.
Bảng giá chi tiết (OpenAI)
GPT Image 1
| Quality | 1024×1024 | 1024×1536 | 1536×1024 |
|---|---|---|---|
| Low | $0.011 | $0.016 | $0.016 |
| Medium | $0.042 | $0.063 | $0.063 |
| High | $0.167 | $0.250 | $0.250 |
GPT Image 1.5 (rẻ hơn GPT Image 1)
| Quality | 1024×1024 | 1024×1536 | 1536×1024 |
|---|---|---|---|
| Low | $0.009 | $0.013 | $0.013 |
| Medium | $0.034 | $0.050 | $0.050 |
| High | $0.133 | $0.200 | $0.200 |
GPT Image 2 (thế hệ mới nhất)
Giá theo quality × độ phân giải (cập nhật 30/07/2026). Khung hình (aspect ratio) không ảnh hưởng giá — chỉ quality và resolution:
| Quality | 1K | 2K | 4K |
|---|---|---|---|
| Low | $0.050 | $0.060 | $0.070 |
| Medium | $0.085 | $0.160 | $0.250 |
| High | $0.270 | $0.540 | $0.800 |
💡
resolutionlà tham số riêng (1K/2K/4K), tách khỏisize(khung hình). Mặc định1K. 2K/4K nét hơn nhưng đắt hơn.
GPT Image 1 Mini (rẻ nhất)
| Quality | 1024×1024 | 1024×1536 | 1536×1024 |
|---|---|---|---|
| Low | $0.005 | $0.007 | $0.007 |
| Medium | $0.015 | $0.023 | $0.023 |
| High | $0.036 | $0.052 | $0.052 |
DALL-E 3
| Quality | 1024×1024 | 1024×1536 / 1536×1024 | 1024×1792 / 1792×1024 |
|---|---|---|---|
| Standard | $0.040 | $0.080 | $0.080 |
| HD | $0.080 | $0.120 | $0.120 |
Tham số nâng cao: background & output_format
Hai tham số tùy chọn cho GPT Image 2 (gpt-image-2) — kiểm soát nền và định dạng file ảnh trả về:
| Tham số | Giá trị | Mặc định | Ý nghĩa |
|---|---|---|---|
background | auto / transparent / opaque | auto | transparent = nền trong suốt (tách nền sẵn); opaque = nền đặc; auto = để model tự quyết |
output_format | png / jpeg / webp | png | Định dạng file ảnh trả về |
💡 Muốn ảnh nền trong suốt (tách nền sẵn): gửi
"background": "transparent"kèm"output_format": "png"(hoặcwebp). Tránhjpegvì JPEG không hỗ trợ kênh alpha → nền trong suốt sẽ bị thành đen/trắng.
Ví dụ: Ảnh nền trong suốt (PNG transparent)
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A cute 3D cartoon mascot bee, centered, full body",
"background": "transparent",
"output_format": "png"
}'
Ví dụ: Xuất ảnh JPEG (file nhẹ hơn, có nền)
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Professional product photo of a coffee mug on a wooden table",
"output_format": "jpeg"
}'
ℹ️ Nếu gửi giá trị không hợp lệ cho
output_format(vdgif) → hệ thống tự dùngpng. Các model không phảigpt-image-2sẽ bỏ quaoutput_format(luôn trảpng).
Ví dụ 1: Tạo ảnh cơ bản với GPT Image 1.5
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-1.5",
"prompt": "Một con mèo đang ngồi trên mặt trăng, phong cách anime"
}'
ℹ️ Không cần truyền
sizehayquality— mặc định là1024x1024vàauto.
Ví dụ 2: Ảnh HD với DALL-E 3
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "dall-e-3",
"prompt": "A cyberpunk cityscape at sunset with neon lights reflecting on wet streets",
"size": "1792x1024",
"quality": "hd"
}'
Ví dụ 3: Ảnh giá rẻ với GPT Image 1 Mini
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-1-mini",
"prompt": "Logo đơn giản cho quán cà phê với hình hạt cà phê",
"quality": "low"
}'
💡 Tip: GPT Image 1 Mini ở quality
lowchỉ $0.005/ảnh — rẻ nhất trong tất cả models!
Ví dụ 4: Dùng SDK
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-xxxxxx",
base_url="https://platform.beeknoee.com/v1"
)
response = client.images.generate(
model="gpt-image-1.5",
prompt="Bức tranh sơn dầu phong cảnh Hà Nội mùa thu",
size="1024x1024",
quality="high",
n=1,
)
# Lấy URL ảnh (hoặc base64 tùy model)
image_url = response.data[0].url
print(f"Image URL: {image_url}")
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'sk-bee-xxxxxx',
baseURL: 'https://platform.beeknoee.com/v1',
});
const response = await client.images.generate({
model: 'gpt-image-1.5',
prompt: 'Cute robot painting a landscape, studio ghibli style',
size: '1024x1536',
quality: 'medium',
});
console.log(response.data[0].url);
Cấu hình cho Google Gemini Models
⚠️ Quan trọng: Google Gemini Models sử dụng cùng endpoint với OpenAI nhưng có một số khác biệt:
- Chỉ cần truyền
size(VD:2048x2048) — hệ thống tự xác định tỷ lệ phù hợp- Không hỗ trợ
quality,style,n(luôn tạo 1 ảnh)- Trả về
base64(không phải URL)- Hỗ trợ 3 mức độ phân giải: 1K, 2K, 4K
Parameters (Google)
| Tham số | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|
model | ✅ | — | Tên model (VD: gemini-3.1-flash-image-preview) |
prompt | ✅ | — | Mô tả ảnh cần tạo |
size | ❌ | 1024x1024 | Kích thước ảnh (xem bảng bên dưới) |
image_urls | ❌ | — | 🆕 Mảng ảnh đầu vào để sửa ảnh (image-to-image) — xem mục riêng |
🔑 Các tham số
quality,style,nsẽ bị bỏ qua khi dùng Google models.
Sizes hỗ trợ (Google Gemini)
1K Resolution (mặc định)
| Size | Tỷ lệ |
|---|---|
1024x1024 | 1:1 |
768x1024 | 3:4 |
1024x768 | 4:3 |
576x1024 | 9:16 |
1024x576 | 16:9 |
2K Resolution
| Size | Tỷ lệ |
|---|---|
2048x2048 | 1:1 |
1536x2048 | 3:4 |
2048x1536 | 4:3 |
1152x2048 | 9:16 |
2048x1152 | 16:9 |
4K Resolution
| Size | Tỷ lệ |
|---|---|
4096x4096 | 1:1 |
3072x4096 | 3:4 |
4096x3072 | 4:3 |
Bảng giá chi tiết (Google)
| Model | Giá/ảnh 1K | Giá/ảnh 2K | Giá/ảnh 4K |
|---|---|---|---|
| Gemini 3.1 Flash Image | $0.067 | $0.101 | $0.151 |
| Gemini 3 Pro Image | $0.134 | $0.134 | $0.240 |
| Gemini 2.5 Flash Image | $0.039 | $0.058 | $0.087 |
| Imagen 3 Fast | $0.030 | $0.030 | $0.030 |
💡 Gemini 2.5 Flash Image là lựa chọn giá rẻ nhất cho ảnh 1K ($0.039) từ Google.
Ví dụ 6: Tạo ảnh Gemini cơ bản
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview",
"prompt": "Phong cảnh đồi chè Mộc Châu lúc bình minh, sương mù"
}'
Ví dụ 7: Ảnh 2K (2048x2048)
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview",
"prompt": "Detailed digital painting of a Vietnamese dragon",
"size": "2048x2048"
}'
ℹ️ Size
2048x2048tự động map thành tỷ lệ1:1ở 2K resolution — giá $0.101/ảnh.
Ví dụ 8: Ảnh 4K dọc (Portrait)
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "Beautiful portrait of a Vietnamese woman in ao dai, sakura background",
"size": "3072x4096"
}'
Ví dụ 9: Ảnh panorama 16:9 (Google)
curl -X POST https://platform.beeknoee.com/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-2.5-flash-image",
"prompt": "Panoramic view of Ha Long Bay at golden hour, dramatic clouds",
"size": "2048x1152"
}'
Ví dụ 10: Python SDK (Google model)
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-xxxxxx",
base_url="https://platform.beeknoee.com/v1"
)
# Dùng đúng SDK OpenAI, chỉ đổi model name
response = client.images.generate(
model="gemini-2.5-flash-image",
prompt="Cute chibi cat astronaut floating in space with stars",
size="1024x1024", # 1K, giá chỉ $0.039
)
# Google models trả base64
import base64
image_data = base64.b64decode(response.data[0].b64_json)
with open("output.png", "wb") as f:
f.write(image_data)
print("Saved output.png!")
Endpoints phụ trợ
Xem danh sách model ảnh
curl https://platform.beeknoee.com/v1/models \
-H "Authorization: Bearer sk-bee-xxxxxx"
Lấy hàng loạt ảnh đã tạo (list)
Trả về danh sách ảnh bạn đã tạo, mới nhất trước — dùng để tự dựng thư viện ảnh của riêng bạn.
curl "https://platform.beeknoee.com/v1/image/generations?limit=20&offset=0" \
-H "Authorization: Bearer sk-bee-xxxxxx"
Query params:
| Tham số | Mặc định | Ghi chú |
|---|---|---|
limit | 20 | tối đa 100 |
offset | 0 | phân trang — 0, 20, 40… |
status | (không lọc) | PROCESSING · COMPLETED · FAILED. Giá trị lạ bị bỏ qua. |
Response:
{
"jobs": [
{
"job_id": "a1b2c3d4-...",
"status": "COMPLETED",
"model": "bee/gpt-image-2",
"model_name": "GPT Image 2",
"supplier": "beeknoee",
"prompt": "a cinematic sunset...",
"size": "1024x1024",
"quality": "high",
"cost_vnd": 1500,
"data": [{ "url": "/v1/image/generations/a1b2c3d4-.../download?index=0" }],
"cache_expires_at": "2026-07-11T10:00:00.000Z",
"created_at": "2026-07-08T10:00:00.000Z"
}
],
"total": 42,
"limit": 20,
"offset": 0
}
model là id kỹ thuật để gọi API; model_name là tên hiển thị cho người đọc; supplier là nhà cung cấp (chữ thường).
Lấy đúng ảnh đang tạo — tiện để dựng màn hình "đang xử lý" mà không phải tải cả trang lịch sử:
curl "https://platform.beeknoee.com/v1/image/generations?status=PROCESSING" \
-H "Authorization: Bearer sk-bee-xxxxxx"
Lấy đúng ảnh đã xong — nên dùng cái này khi dựng thư viện, thay vì lấy tất rồi tự lọc (lấy tất thì các job hỏng/đang chạy chiếm mất chỗ trong limit):
curl "https://platform.beeknoee.com/v1/image/generations?status=COMPLETED&limit=50" \
-H "Authorization: Bearer sk-bee-xxxxxx"
💡 Mỗi
data[].urllà đường dẫn download sẵn sàng (ghép domainhttps://platform.beeknoee.com/apivào đầu). Lặpoffsetđể lấy hết. Duyệt danh sách rồi tải từng ảnh như bên dưới là bạn "get hàng loạt" được toàn bộ ảnh.
Download ảnh
curl "https://platform.beeknoee.com/v1/image/generations/{job_id}/download?index=0" \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-o image.png
⏳ Thời gian lưu ảnh & Thư viện
- Ảnh được lưu 3 ngày kể từ lúc tạo, sau đó tự động xóa để tiết kiệm dung lượng — hãy tải về sớm.
- Xem lại toàn bộ ảnh đã tạo (còn hạn) ngay trên dashboard tại trang Thư viện: Playground - Media → Thư viện. Trang này hiển thị thumbnail, model, thông số, thời gian còn lại và nút tải nhanh. Media đã hết hạn sẽ tự ẩn.
- Ảnh đã quá 3 ngày sẽ không tải được nữa (endpoint download trả lỗi "Ảnh đã hết hạn").
📸 Gửi ảnh kèm theo (Image Input) — Image-to-Image
Ngoài tạo ảnh thuần từ text, Beeknoee hỗ trợ gửi ảnh có sẵn kèm prompt để chỉnh sửa, biến đổi, hoặc lấy ảnh làm tham chiếu.
Tổng quan: Endpoint nào hỗ trợ gửi ảnh?
| Endpoint | Gửi ảnh? | Cách gửi | Models hỗ trợ |
|---|---|---|---|
POST /v1/image/edits | ✅ Có | multipart/form-data (file upload hoặc base64) | gpt-image-1, gpt-image-1.5, gpt-image-2, gpt-image-1-mini, chatgpt-image-latest, dall-e-2 |
POST /v1/image/generations | ✅ Có (qua image_urls) | JSON body (prompt + image_urls) | gemini-3-pro-image-preview, gemini-3.1-flash-image-preview, gemini-2.5-flash-image, flux-2-pro, flux-2-flex, seedream-5-lite, seedream-4.5, wan-2.7-image, grok-imagine, bee/gpt-image-1.5 |
POST /v1/image/generations | ❌ Chỉ text | JSON body (chỉ prompt) | Tất cả models khác |
⚠️ Lưu ý quan trọng: Mỗi provider dùng endpoint khác nhau để gửi ảnh:
- OpenAI models (gpt-image-1/1.5/2, dall-e): Dùng
/v1/image/edits+ upload file- Google Gemini / Flux 2 / Seedream / Wan / Grok: Dùng
/v1/image/generations+ truyềnimage_urls(URL công khai hoặc data URI)🆕 Google Gemini nay đã sửa được ảnh — xem mục Image-to-Image — Google Gemini bên dưới.
🍌 Image-to-Image — Google Gemini (Nano Banana)
Cả 3 model ảnh Gemini đều sửa được ảnh: gửi ảnh có sẵn + prompt mô tả thay đổi, qua param image_urls trong endpoint /v1/image/generations (không dùng /v1/image/edits).
Models hỗ trợ
| Model | Số ảnh input tối đa | Giá/ảnh 1K → 4K | Đặc điểm |
|---|---|---|---|
gemini-3-pro-image-preview | 8 | $0.134 → $0.240 | Chất lượng cao nhất, bám prompt phức tạp tốt |
gemini-3.1-flash-image-preview | 10 | $0.067 → $0.151 | Cân bằng chất lượng/tốc độ |
gemini-2.5-flash-image | 10 | $0.039 → $0.087 | Rẻ nhất |
💰 Giá sửa ảnh tính bằng giá tạo ảnh (theo
size), không có bảng giá editing riêng như OpenAI.
Parameters
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
model | ✅ | Một trong 3 model ở bảng trên |
prompt | ✅ | Mô tả thay đổi cần thực hiện trên ảnh |
image_urls | ✅ | Mảng ảnh đầu vào — URL công khai (https://...) hoặc data URI (data:image/png;base64,...). Mỗi ảnh ≤ 20MB |
size | ❌ | Bỏ trống = giữ nguyên tỉ lệ ảnh gốc (khuyến nghị). Truyền vào = ép ảnh ra đúng tỉ lệ đó |
⭐ Mẹo quan trọng — khi nào nên bỏ
size: khi sửa ảnh mà bạn muốn giữ bố cục gốc (đổi màu, thêm/xoá vật thể, đổi phong cách), đừng gửisize— ảnh sẽ giữ đúng tỉ lệ ban đầu. Chỉ gửisizekhi bạn cố ý muốn đổi khung hình (VD: ảnh vuông → ảnh ngang 16:9).
Ví dụ 1: Sửa ảnh từ URL — giữ nguyên tỉ lệ (cURL)
curl -X POST https://platform.beeknoee.com/api/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image-preview",
"prompt": "Đổi màu chiếc áo thành xanh dương, giữ nguyên mọi thứ khác",
"image_urls": ["https://cdn.example.com/portrait.jpg"]
}'
Không truyền
size→ ảnh kết quả giữ đúng tỉ lệ ảnh gốc.
Ví dụ 2: Ghép nhiều ảnh tham chiếu (cURL)
curl -X POST https://platform.beeknoee.com/api/v1/image/generations \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image-preview",
"prompt": "Đặt sản phẩm ở ảnh 1 vào khung cảnh của ảnh 2, ánh sáng tự nhiên",
"image_urls": [
"https://cdn.example.com/product.png",
"https://cdn.example.com/scene.jpg"
]
}'
Ví dụ 3: Gửi ảnh từ máy (base64) — Python
import base64, requests
def to_data_uri(path: str, mime: str = "image/png") -> str:
with open(path, "rb") as f:
return f"data:{mime};base64,{base64.b64encode(f.read()).decode()}"
res = requests.post(
"https://platform.beeknoee.com/api/v1/image/generations",
headers={
"Authorization": "Bearer sk-bee-xxxxxx",
"Content-Type": "application/json",
},
json={
"model": "gemini-2.5-flash-image",
"prompt": "Xoá phông nền, thay bằng nền trắng studio",
"image_urls": [to_data_uri("./anh-cua-toi.jpg", "image/jpeg")],
# Bỏ "size" để giữ nguyên tỉ lệ ảnh gốc
},
timeout=300,
)
data = res.json()
print("Job:", data.get("job_id"), "| Chi phí:", data.get("cost_vnd"), "đ")
# Ảnh trả về dạng base64 trong data[0].b64_json
b64 = data["data"][0].get("b64_json")
if b64:
with open("ket-qua.png", "wb") as f:
f.write(base64.b64decode(b64))
print("Đã lưu: ket-qua.png")
Ví dụ 4: Đổi khung hình (có truyền size) — JavaScript
const res = await fetch('https://platform.beeknoee.com/api/v1/image/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-bee-xxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'gemini-3-pro-image-preview',
prompt: 'Mở rộng khung cảnh sang hai bên, giữ nguyên chủ thể ở giữa',
image_urls: ['https://cdn.example.com/square-photo.jpg'],
size: '1024x576', // ép ảnh vuông → khung ngang 16:9
}),
});
const data = await res.json();
console.log('Chi phí:', data.cost_vnd, 'đ');
Sizes hỗ trợ khi sửa ảnh
Giống hệt lúc tạo ảnh — xem Sizes hỗ trợ (Google Gemini). Nhắc lại: bỏ trống size thì giữ tỉ lệ ảnh gốc.
Lưu ý
| Vấn đề | Giải thích |
|---|---|
n luôn = 1 | 3 model này chỉ tạo 1 ảnh mỗi request. Gửi n > 1 sẽ bị trả lỗi 400 (không âm thầm tính tiền thừa) |
Không dùng /v1/image/edits | Endpoint đó chỉ dành cho model OpenAI. Gọi Gemini vào đó sẽ báo "không hỗ trợ image editing" |
Không hỗ trợ mask | Muốn sửa vùng cụ thể thì mô tả bằng lời trong prompt (VD: "chỉ đổi màu chiếc mũ ở góc trên bên trái") |
| Ảnh ≤ 20MB | Vượt quá sẽ bị từ chối ngay, không tính phí |
Lỗi IMAGE_RECITATION | Google từ chối khi ảnh input trùng nội dung có bản quyền (ảnh stock, nhân vật nổi tiếng…). Đổi ảnh khác |
| Lỗi bộ lọc an toàn | Google chặn nội dung nhạy cảm — thông báo lỗi sẽ ghi rõ lý do |
🔄 Image-to-Image — Flux 2 & Seedream (qua image_urls)
Flux 2 (Black Forest Labs) và Seedream (ByteDance) hỗ trợ image-to-image qua param image_urls trong endpoint /v1/image/generations.
✅ Hỗ trợ cả 2 cách gửi ảnh
| Cách gửi | Ví dụ | Backend xử lý |
|---|---|---|
| URL công khai | "https://cdn.example.com/photo.jpg" | Gửi thẳng tới model provider |
| Data URI (base64) | "data:image/png;base64,iVBOR..." | Tự upload lên bộ nhớ tạm → lấy URL → gửi model provider |
💡 Backend tự động xử lý! User upload file bình thường qua Test Console hoặc gửi data URI qua API — backend sẽ tự upload lên bộ nhớ tạm rồi lấy URL. Không cần tự host ảnh.
Luồng xử lý (architecture)
User gửi image_urls: ["data:image/png;base64,..."]
│
▼
Backend nhận request
│
├── URL bắt đầu http(s):// → pass through (giữ nguyên)
│
└── URL bắt đầu data: → tự upload lên bộ nhớ tạm
│ → nhận fileUrl công khai (tự hết hạn)
│
▼
Gửi model provider tạo ảnh với input_urls = [fileUrl]
│
▼
Poll kết quả → trả ảnh cho user
Models hỗ trợ
| Model | Provider | Giá/ảnh | Đặc điểm |
|---|---|---|---|
flux-2-pro | Black Forest Labs | $0.05 (1K) / $0.07 (2K) | Chất lượng cao |
flux-2-flex | Black Forest Labs | $0.14 (1K) / $0.24 (2K) | Linh hoạt, đa phong cách |
seedream-5-lite | ByteDance | $0.045 (2K) / $0.068 (4K) | Nhanh, giá rẻ |
seedream-4.5 | ByteDance | $0.05 (2K) / $0.08 (4K) | Chất lượng cao hơn |
Parameters
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
model | ✅ | Tên model (VD: flux-2-pro) |
prompt | ✅ | Mô tả ảnh mới cần tạo dựa trên ảnh đầu vào |
image_urls | ✅ | Mảng URL ảnh (HTTP/HTTPS hoặc data URI). Flux 2: tối đa 8 ảnh, Seedream: tối đa 14 ảnh |
size | ❌ | Kích thước ảnh output (mặc định: 1024x1024) |
quality | ❌ | Flux 2: medium (1K) / high (2K). Seedream: basic (2K) / high (4K) |
Ví dụ 1: Flux 2 Pro — Image-to-Image với URL (cURL)
curl -s -X POST "https://platform.beeknoee.com/v1/image/generations" \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2-pro",
"prompt": "Transform this photo into a beautiful oil painting style, keep the same composition",
"image_urls": ["https://example.com/my-photo.jpg"],
"quality": "medium"
}'
Ví dụ 2: Flux 2 Pro — Nhiều ảnh tham chiếu (cURL)
Gửi nhiều ảnh (1-8) để model tham chiếu — ví dụ: lấy sản phẩm ở ảnh 1 đặt vào bối cảnh ảnh 2:
curl -s -X POST "https://platform.beeknoee.com/v1/image/generations" \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2-pro",
"prompt": "The jar in image 1 is filled with capsules exactly same as image 2 with the exact logo",
"image_urls": [
"https://cdn.example.com/photos/jar.png",
"https://cdn.example.com/photos/capsules.png"
],
"quality": "high"
}'
💡 Prompt tip: Khi dùng nhiều ảnh, tham chiếu bằng "image 1", "image 2"... trong prompt để chỉ rõ ảnh nào dùng cho mục đích gì.
Ví dụ 3: Gửi data URI (base64) — Backend auto-upload
import requests
import base64
# Đọc file ảnh local → base64 data URI
with open("my-photo.jpg", "rb") as f:
data_uri = f"data:image/jpeg;base64,{base64.b64encode(f.read()).decode()}"
response = requests.post(
"https://platform.beeknoee.com/v1/image/generations",
headers={
"Authorization": "Bearer sk-bee-xxxxxx",
"Content-Type": "application/json",
},
json={
"model": "flux-2-pro",
"prompt": "Chuyển ảnh này sang phong cách quảng cáo chuyên nghiệp, nền gradient",
"image_urls": [data_uri], # Backend tự upload lên bộ nhớ tạm
"quality": "medium",
"size": "1024x1024",
},
)
result = response.json()
print(result)
Ví dụ 4: Image-to-Image qua image_urls
import requests
response = requests.post(
"https://platform.beeknoee.com/v1/image/generations",
headers={
"Authorization": "Bearer sk-bee-xxxxxx",
"Content-Type": "application/json",
},
json={
"model": "seedream-5-lite",
"prompt": "Enhance this photo to anime style, vibrant colors",
"image_urls": ["https://example.com/my-photo.jpg"],
"quality": "basic",
},
)
print(response.json())
const response = await fetch('https://platform.beeknoee.com/v1/image/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-bee-xxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'flux-2-pro',
prompt: 'Create a cyberpunk version of this photo with neon lighting',
image_urls: ['https://example.com/photo.jpg'],
quality: 'high',
size: '1024x1536',
}),
});
console.log(await response.json());
So sánh: /v1/image/edits vs image_urls
/v1/image/edits (OpenAI) | image_urls (Gemini/Flux 2/Seedream…) | |
|---|---|---|
| Gửi ảnh | Upload file (multipart) | URL hoặc data URI (JSON) |
| Số ảnh | Tối đa 16 file | Gemini Pro: 8, Gemini Flash: 10, Flux 2: 8, Seedream: 14 |
| Mask | ✅ Hỗ trợ | ❌ Không |
| Endpoint | /v1/image/edits | /v1/image/generations |
| Content-Type | multipart/form-data | application/json |
| Data URI | ❌ Không | ✅ Backend auto-upload |
| Giữ tỉ lệ ảnh gốc | ❌ Luôn theo size | ✅ Bỏ size là giữ nguyên (Gemini) |
Yêu cầu cho image_urls
| Yêu cầu | Chi tiết |
|---|---|
| Định dạng | http(s):// URL hoặc data:image/...;base64,... URI |
| File types | image/jpeg, image/png, image/webp |
| Max file size | 10 MB / file (Gemini: 20 MB) |
| Số lượng | Gemini 3 Pro: 8, Gemini Flash (3.1 / 2.5): 10, Flux 2: 8, Seedream: 14 |
⚠️ Troubleshooting
| Lỗi | Nguyên nhân | Cách fix |
|---|---|---|
input_urls file type not supported | Gửi SVG, GIF hoặc data URI sai format | Dùng JPEG/PNG/WebP. Nếu data URI: kiểm tra format data:image/jpeg;base64,... |
Model không hỗ trợ image editing | Gửi Flux 2/Seedream đến /v1/image/edits | Dùng /v1/image/generations + image_urls |
| Ảnh output không giống input | Không có image_urls trong request | Kiểm tra đã gửi image_urls — dùng Test Console ở chế độ "🖌️ Chỉnh sửa ảnh" |
Upload ảnh lên provider storage thất bại | Data URI quá lớn hoặc bộ nhớ tạm lỗi | Thử dùng URL công khai thay vì data URI |
🖼️ Text-to-Image / Image-to-Image — Wan 2.7 (Alibaba)
Wan 2.7 Image (Alibaba) hỗ trợ text-to-image và image-to-image (tối đa 9 ảnh reference) qua image_urls trong /v1/image/generations.
Models
| Model | Giá/ảnh | Đặc điểm |
|---|---|---|
wan-2.7-image | $0.030 | Text-to-Image + Image-to-Image (tối đa 9 ảnh), 2K |
wan-2.7-image-pro | $0.075 | Text-to-Image only, lên tới 4K |
Parameters
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
model | ✅ | wan-2.7-image hoặc wan-2.7-image-pro |
prompt | ✅ | Mô tả ảnh cần tạo |
image_urls | ❌ | Mảng URL/data URI (chỉ wan-2.7-image, tối đa 9 ảnh) |
size | ❌ | Kích thước output (mặc định: 1024x1024) |
quality | ❌ | medium (1K) / high (2K) |
n | ❌ | Số ảnh tạo (1-4, mặc định: 1). Tính tiền = giá × n |
Ví dụ: Wan 2.7 — Text-to-Image
curl -s -X POST "https://platform.beeknoee.com/v1/image/generations" \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "wan-2.7-image",
"prompt": "A cozy coffee shop interior with warm lighting and wooden furniture",
"quality": "medium",
"n": 1
}'
Ví dụ: Wan 2.7 — Image-to-Image (multi-reference)
import requests
response = requests.post(
"https://platform.beeknoee.com/v1/image/generations",
headers={
"Authorization": "Bearer sk-bee-xxxxxx",
"Content-Type": "application/json",
},
json={
"model": "wan-2.7-image",
"prompt": "Combine the style of image 1 with the subject in image 2, keep composition consistent",
"image_urls": [
"https://example.com/style-ref.jpg",
"https://example.com/subject.jpg"
],
"quality": "high",
},
)
print(response.json())
Sizes hỗ trợ (Wan 2.7)
| Size | Tỷ lệ |
|---|---|
1024x1024 | 1:1 |
768x1024 | 3:4 |
1024x768 | 4:3 |
576x1024 | 9:16 |
1024x576 | 16:9 |
1792x768 | 21:9 |
auto | 1:1 (mặc định) |
💡 Wan 2.7 I2I: Dùng
image_urls(tối đa 9 ảnh) để tham chiếu — hỗ trợ cả URL công khai lẫn data URI (backend auto-upload).💡 Nhiều ảnh: Hỗ trợ
n=1-4ảnh cùng lúc. Ví dụ"n": 3→ tạo 3 ảnh, tính tiền 3×$0.030=$0.090.
🎨 Text-to-Image / Image-to-Image — Grok Imagine (xAI)
Grok Imagine (xAI) hỗ trợ text-to-image và image-to-image qua /v1/image/generations.
Models
| Model | Giá/ảnh | Đặc điểm |
|---|---|---|
grok-imagine | T2I: $0.025, I2I: $0.030 | Auto-switch T2I/I2I dựa trên image_urls |
grok-imagine-quality | $0.050 | High-fidelity text-to-image, 2K |
💡
grok-imaginetự động chuyển sang Image-to-Image khi cóimage_urlstrong request.
Parameters
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
model | ✅ | grok-imagine hoặc grok-imagine-quality |
prompt | ✅ | Mô tả ảnh cần tạo/chỉnh sửa |
image_urls | ❌ | Mảng URL/data URI (chỉ grok-imagine, tối đa 3 ảnh, auto-switch sang I2I) |
size | ❌ | Kích thước output (mặc định: 1024x1024) |
n | ❌ | Số ảnh tạo (1-4, mặc định: 1) |
Sizes hỗ trợ (Grok Imagine)
| Size | Tỷ lệ |
|---|---|
1024x1024 | 1:1 |
1536x1024 | 3:2 |
1024x1536 | 2:3 |
576x1024 | 9:16 |
1024x576 | 16:9 |
auto | 1:1 (mặc định) |
Ví dụ: Grok Imagine — Text-to-Image
curl -s -X POST "https://platform.beeknoee.com/v1/image/generations" \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine",
"prompt": "A futuristic cityscape at sunset with flying cars and neon lights",
"n": 2
}'
💡
n=2sẽ tạo 2 ảnh và tính tiền 2×$0.025=$0.050. Mặc địnhn=1nếu không gửi.
Ví dụ: Grok Imagine Quality — High-fidelity
import requests
response = requests.post(
"https://platform.beeknoee.com/v1/image/generations",
headers={
"Authorization": "Bearer sk-bee-xxxxxx",
"Content-Type": "application/json",
},
json={
"model": "grok-imagine-quality",
"prompt": "Professional product photography of a luxury watch on marble surface",
"size": "1024x1024",
},
)
print(response.json())
Ví dụ: Grok Imagine — Image-to-Image
const response = await fetch('https://platform.beeknoee.com/v1/image/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-bee-xxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'grok-imagine',
prompt: 'Transform this photo into cyberpunk style with neon lighting',
image_urls: ['https://example.com/my-photo.jpg'],
}),
});
console.log(await response.json());
Image Editing — Chỉnh sửa ảnh / Image-to-Image
POST https://platform.beeknoee.com/v1/image/edits
Content-Type: multipart/form-data
ℹ️ Mục này dành cho model OpenAI (
gpt-image-1/1.5/2,gpt-image-1-mini,chatgpt-image-latest,dall-e-2). Sửa ảnh bằng Google Gemini → dùng/v1/image/generations+image_urls, xem mục riêng.
Gửi ảnh có sẵn + prompt mô tả → nhận ảnh mới. Hỗ trợ nhiều use case:
| Use case | Cách dùng |
|---|---|
| 🖌️ Chỉnh sửa ảnh | Gửi image + prompt mô tả phần cần sửa |
| 🎭 Chuyển style | Gửi image + prompt mô tả style mới (VD: "chuyển sang phong cách anime") |
| 🏞️ Thay nền | Gửi image + mask (vùng nền transparent) + prompt mô tả nền mới |
| 🗑️ Xóa đối tượng | Gửi image + mask (vùng cần xóa) + prompt = "xóa đối tượng, giữ nền" |
| ➕ Thêm chi tiết | Gửi image + prompt = "thêm kính mát cho nhân vật" |
| 🎨 Color grading | Gửi image + prompt = "chỉnh tone ảnh warm, hoàng hôn" |
Parameters
| Tham số | Bắt buộc | Mô tả |
|---|---|---|
image | ✅ | File ảnh gốc — PNG/JPEG (≤ 4MB) |
prompt | ✅ | Mô tả thay đổi cần thực hiện trên ảnh |
mask | ❌ | File PNG mask — vùng transparent = vùng cần chỉnh sửa |
model | ❌ | Mặc định gpt-image-1. Hỗ trợ: gpt-image-1, gpt-image-1.5, gpt-image-2, gpt-image-1-mini, chatgpt-image-latest, dall-e-2 |
size | ❌ | Kích thước ảnh output (mặc định: 1024x1024) |
quality | ❌ | low / medium / high / auto (GPT Image models). dall-e-2 luôn standard |
n | ❌ | Số ảnh kết quả (mặc định: 1) |
Bảng giá Editing
| Model | Quality | 1024×1024 | 1024×1536 |
|---|---|---|---|
gpt-image-1 | Low | $0.014 | $0.019 |
gpt-image-1 | Medium | $0.050 | $0.076 |
gpt-image-1 | High | $0.200 | $0.300 |
dall-e-2 | Standard | $0.020 | — |
💡 Các model
gpt-image-1.5,gpt-image-2,gpt-image-1-mini,chatgpt-image-latestcũng hỗ trợ editing với giá tương ứng bảng generation.
Cách 1: Upload file trực tiếp (cURL)
Cách đơn giản nhất — dùng -F để upload file từ ổ đĩa:
# Chỉnh sửa ảnh (không mask — AI tự xác định vùng cần sửa)
curl -X POST https://platform.beeknoee.com/v1/image/edits \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-F "[email protected]" \
-F "prompt=Chuyển ảnh sang phong cách tranh sơn dầu" \
-F "model=gpt-image-1" \
-F "quality=medium"
# Chỉnh sửa có mask (inpainting — chỉ sửa vùng được đánh dấu)
curl -X POST https://platform.beeknoee.com/v1/image/edits \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-F "[email protected]" \
-F "[email protected]" \
-F "prompt=Thay nền thành bãi biển hoàng hôn" \
-F "model=gpt-image-1" \
-F "size=1024x1024" \
-F "quality=medium"
Cách 2: Upload file — Python
import requests
# ═══ Upload file từ ổ đĩa ═══
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files={
"image": ("photo.png", open("photo.png", "rb"), "image/png"),
},
data={
"prompt": "Thêm kính mát cho nhân vật trong ảnh",
"model": "gpt-image-1",
"size": "1024x1024",
"quality": "medium",
},
)
print(response.json())
# ═══ Upload file + mask (inpainting) ═══
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files={
"image": ("photo.png", open("photo.png", "rb"), "image/png"),
"mask": ("mask.png", open("mask.png", "rb"), "image/png"),
},
data={
"prompt": "Thay background thành phòng làm việc hiện đại",
"model": "gpt-image-1",
"quality": "high",
},
)
Cách 3: Gửi ảnh dạng Base64 — Python
Khi ảnh không nằm trên ổ đĩa (ví dụ: từ database, download từ URL, hoặc tạo từ code), bạn có thể chuyển thành base64 rồi gửi dưới dạng file trong multipart/form-data:
import requests
import base64
from io import BytesIO
# ═══ Từ base64 string ═══
base64_image = "iVBORw0KGgoAAAANSUhEUg..." # base64 string của ảnh
# Decode base64 → bytes → gửi như file
image_bytes = base64.b64decode(base64_image)
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files={
"image": ("input.png", BytesIO(image_bytes), "image/png"),
},
data={
"prompt": "Chuyển ảnh sang style anime Ghibli",
"model": "gpt-image-1",
"quality": "high",
},
)
result = response.json()
print(result)
# ═══ Từ URL (download → gửi) ═══
import requests
from io import BytesIO
image_url = "https://example.com/my-photo.jpg"
img_response = requests.get(image_url)
image_bytes = img_response.content
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files={
"image": ("downloaded.png", BytesIO(image_bytes), "image/png"),
},
data={
"prompt": "Xóa tất cả text/watermark trong ảnh",
"model": "gpt-image-1",
"quality": "medium",
},
)
Cách 4: Gửi ảnh dạng Base64 — JavaScript (Node.js)
const fs = require('fs');
// ═══ Từ file trên ổ đĩa ═══
const form = new FormData();
form.append('image', new Blob([fs.readFileSync('photo.png')], { type: 'image/png' }), 'photo.png');
form.append('prompt', 'Chuyển ảnh sang phong cách cyberpunk neon');
form.append('model', 'gpt-image-1');
form.append('quality', 'medium');
const response = await fetch('https://platform.beeknoee.com/v1/image/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-bee-xxxxxx' },
body: form,
});
console.log(await response.json());
// ═══ Từ base64 string ═══
const base64Image = 'iVBORw0KGgoAAAANSUhEUg...'; // base64 của ảnh
const imageBuffer = Buffer.from(base64Image, 'base64');
const form = new FormData();
form.append('image', new Blob([imageBuffer], { type: 'image/png' }), 'input.png');
form.append('prompt', 'Thêm hiệu ứng tuyết rơi vào ảnh');
form.append('model', 'gpt-image-1');
form.append('quality', 'medium');
const response = await fetch('https://platform.beeknoee.com/v1/image/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-bee-xxxxxx' },
body: form,
});
// ═══ Từ URL (download → gửi) ═══
const imgRes = await fetch('https://example.com/my-photo.jpg');
const imgBuffer = Buffer.from(await imgRes.arrayBuffer());
const form = new FormData();
form.append('image', new Blob([imgBuffer], { type: 'image/jpeg' }), 'photo.jpg');
form.append('prompt', 'Upscale ảnh và tăng độ sắc nét');
form.append('model', 'gpt-image-2');
form.append('quality', 'high');
const response = await fetch('https://platform.beeknoee.com/v1/image/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-bee-xxxxxx' },
body: form,
});
Cách 5: OpenAI Python SDK
from openai import OpenAI
import base64
from pathlib import Path
client = OpenAI(
api_key="sk-bee-xxxxxx",
base_url="https://platform.beeknoee.com/v1"
)
# ═══ Từ file ═══
result = client.images.edit(
model="gpt-image-1",
image=open("photo.png", "rb"),
prompt="Chuyển ảnh sang watercolor painting style",
size="1024x1024",
)
# Download kết quả
image_url = result.data[0].url
print(f"Edited image: {image_url}")
# ═══ Từ base64 (decode → BytesIO → gửi như file) ═══
from io import BytesIO
base64_str = "iVBORw0KGgoAAAANSUhEUg..."
image_bytes = base64.b64decode(base64_str)
result = client.images.edit(
model="gpt-image-1",
image=BytesIO(image_bytes),
prompt="Thêm mũ Giáng sinh cho nhân vật",
quality="medium",
)
Mask là gì? Cách tạo mask
Mask là file PNG cùng kích thước với ảnh gốc, trong đó:
- Vùng transparent (alpha = 0): Vùng AI sẽ chỉnh sửa
- Vùng opaque (alpha = 255): Vùng giữ nguyên
# Tạo mask bằng Python (PIL)
from PIL import Image, ImageDraw
# Tạo mask cho vùng hình chữ nhật ở giữa ảnh
img = Image.open("photo.png")
mask = Image.new("RGBA", img.size, (0, 0, 0, 255)) # Toàn bộ opaque
draw = ImageDraw.Draw(mask)
# Vẽ vùng cần sửa (transparent)
draw.rectangle([200, 200, 800, 800], fill=(0, 0, 0, 0))
mask.save("mask.png")
💡 Không bắt buộc mask: Nếu không gửi
mask, AI sẽ tự xác định vùng cần sửa dựa trên prompt. Thích hợp cho style transfer, color grading, thêm chi tiết.
🖼️ Ảnh làm mẫu (Reference Image) — Tạo ảnh mới dựa trên ảnh tham chiếu
Khi bạn muốn gửi ảnh làm mẫu kèm prompt để AI tạo ảnh mới lấy cảm hứng từ ảnh đó (không phải chỉnh sửa trực tiếp), đây là cách thực hiện:
Nguyên lý
Dùng endpoint /v1/image/edits — gửi ảnh mẫu + prompt mô tả ảnh mới bạn muốn tạo. Không cần mask — AI sẽ dùng ảnh gốc làm ngữ cảnh/tham chiếu.
⚠️ Lưu ý: Endpoint
/v1/image/generationschỉ nhận text prompt, không nhận ảnh. Muốn gửi ảnh kèm → dùng/v1/image/edits.
Ví dụ 1: Ảnh mẫu + prompt style mới (cURL)
# Gửi ảnh sản phẩm → AI tạo ảnh quảng cáo mới dựa trên sản phẩm đó
curl -X POST https://platform.beeknoee.com/v1/image/edits \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-F "[email protected]" \
-F "prompt=Tạo ảnh quảng cáo chuyên nghiệp cho sản phẩm này trên nền gradient tím-hồng, có ánh sáng studio" \
-F "model=gpt-image-1" \
-F "quality=high"
Ví dụ 2: Ảnh mẫu style → tạo ảnh khác cùng style (Python)
import requests
# Gửi ảnh mẫu phong cách → AI tạo ảnh mới theo style đó
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files={
"image": ("style-ref.png", open("style-ref.png", "rb"), "image/png"),
},
data={
"prompt": "Giữ nguyên phong cách nghệ thuật của ảnh này, vẽ một cảnh hoàng hôn trên biển với thuyền buồm",
"model": "gpt-image-1",
"quality": "high",
"size": "1536x1024",
},
)
result = response.json()
print(result)
Ví dụ 3: Ảnh mẫu từ base64 (Python)
import requests
import base64
from io import BytesIO
# Ảnh mẫu dạng base64 (VD: từ database hoặc API khác)
base64_reference = "iVBORw0KGgoAAAANSUhEUg..." # base64 của ảnh mẫu
image_bytes = base64.b64decode(base64_reference)
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files={
"image": ("reference.png", BytesIO(image_bytes), "image/png"),
},
data={
"prompt": "Dựa trên ảnh mẫu này, tạo phiên bản 3D render chất lượng cao",
"model": "gpt-image-2",
"quality": "high",
},
)
Ví dụ 4: Ảnh mẫu từ URL (JavaScript)
// Download ảnh mẫu từ URL → gửi kèm prompt
const refRes = await fetch('https://example.com/style-reference.jpg');
const refBuffer = Buffer.from(await refRes.arrayBuffer());
const form = new FormData();
form.append('image', new Blob([refBuffer], { type: 'image/jpeg' }), 'reference.jpg');
form.append('prompt', 'Lấy phong cách màu sắc và bố cục của ảnh này, tạo một poster phim sci-fi');
form.append('model', 'gpt-image-1');
form.append('quality', 'high');
form.append('size', '1024x1536');
const response = await fetch('https://platform.beeknoee.com/v1/image/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-bee-xxxxxx' },
body: form,
});
console.log(await response.json());
Ví dụ 5: OpenAI Python SDK — Ảnh mẫu
from openai import OpenAI
client = OpenAI(
api_key="sk-bee-xxxxxx",
base_url="https://platform.beeknoee.com/v1"
)
# Gửi ảnh mẫu làm tham chiếu
result = client.images.edit(
model="gpt-image-1",
image=open("my-sketch.png", "rb"),
prompt="Biến bức sketch này thành ảnh thực tế chất lượng cao, giữ nguyên bố cục",
size="1024x1024",
quality="high",
)
print(result.data[0].url)
Tips khi dùng ảnh mẫu
| Tip | Chi tiết |
|---|---|
| 📝 Prompt rõ ràng | Mô tả cụ thể bạn muốn AI lấy gì từ ảnh mẫu: style, màu sắc, bố cục, hay nội dung |
| 🎨 Style transfer | Prompt: "Giữ phong cách nghệ thuật của ảnh này, vẽ [nội dung mới]" |
| 📸 Product shot | Prompt: "Tạo ảnh quảng cáo cho sản phẩm trong ảnh, nền [mô tả]" |
| ✏️ Sketch → Real | Prompt: "Biến sketch/wireframe này thành ảnh thực tế" |
| 🔄 Biến thể | Prompt: "Tạo phiên bản khác của ảnh này với [thay đổi]" |
| ⬆️ Nâng cấp | Prompt: "Nâng cấp ảnh này thành 3D render / HDR / cinematic" |
🖼️🖼️🖼️ Gửi nhiều ảnh tham chiếu (Multi-Image Reference)
Ngoài gửi 1 ảnh, Beeknoee hỗ trợ gửi tối đa 16 ảnh cùng lúc trong 1 request. AI sẽ phân tích tất cả các ảnh đầu vào và tạo ảnh mới dựa trên toàn bộ context.
💡 Khi nào dùng nhiều ảnh?
- Gửi nhiều góc chụp sản phẩm → tạo 1 ảnh quảng cáo tổng hợp
- Gửi nhiều ảnh style → AI kết hợp phong cách
- Gửi ảnh mẫu + ảnh nền → ghép nối thông minh
- Gửi nhiều reference → tạo ảnh mới lấy cảm hứng từ tất cả
Endpoint & Field name
| Số ảnh | Field name | Endpoint |
|---|---|---|
| 1 ảnh | image | POST /v1/image/edits |
| 2-16 ảnh | image (gửi nhiều lần) | POST /v1/image/edits |
⚠️ Hệ thống tự động xử lý: 1 ảnh → field
image, nhiều ảnh → fieldimage[]khi gửi đến provider.
Ví dụ 1: Gửi 3 ảnh tham chiếu (cURL)
# Gửi 3 ảnh sản phẩm → AI tạo 1 ảnh quảng cáo kết hợp
curl -X POST https://platform.beeknoee.com/v1/image/edits \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-F "[email protected]" \
-F "[email protected]" \
-F "[email protected]" \
-F "prompt=Dựa trên 3 ảnh sản phẩm này, tạo 1 banner quảng cáo chuyên nghiệp trên nền gradient tím-hồng" \
-F "model=gpt-image-1" \
-F "quality=high" \
-F "size=1536x1024"
Ví dụ 2: Gửi nhiều ảnh (Python — requests)
import requests
# Gửi 3 ảnh mẫu phong cách → AI kết hợp và tạo ảnh mới
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files=[
("image", ("style1.png", open("style1.png", "rb"), "image/png")),
("image", ("style2.png", open("style2.png", "rb"), "image/png")),
("image", ("style3.png", open("style3.png", "rb"), "image/png")),
],
data={
"prompt": "Kết hợp phong cách nghệ thuật của 3 ảnh mẫu này, tạo 1 bức tranh phong cảnh Hà Nội mùa thu",
"model": "gpt-image-2",
"quality": "high",
"size": "1024x1024",
},
)
result = response.json()
print(result)
Ví dụ 3: Gửi nhiều ảnh từ base64 (Python)
import requests
import base64
from io import BytesIO
# Ảnh từ database hoặc API khác (base64)
images_b64 = [
"iVBORw0KGgoAAAANSUhEUg...", # ảnh 1
"iVBORw0KGgoAAAANSUhEUg...", # ảnh 2
"iVBORw0KGgoAAAANSUhEUg...", # ảnh 3
]
files = [
("image", (f"ref{i+1}.png", BytesIO(base64.b64decode(b64)), "image/png"))
for i, b64 in enumerate(images_b64)
]
response = requests.post(
"https://platform.beeknoee.com/v1/image/edits",
headers={"Authorization": "Bearer sk-bee-xxxxxx"},
files=files,
data={
"prompt": "Phân tích 3 ảnh mẫu và tạo 1 ảnh mới kết hợp tất cả yếu tố nổi bật",
"model": "gpt-image-1",
"quality": "high",
},
)
Ví dụ 4: Gửi nhiều ảnh (JavaScript/Node.js)
const fs = require('fs');
const form = new FormData();
// Append nhiều ảnh cùng field name "image"
const imageFiles = ['photo1.png', 'photo2.png', 'photo3.png'];
for (const file of imageFiles) {
form.append('image', new Blob([fs.readFileSync(file)], { type: 'image/png' }), file);
}
form.append('prompt', 'Tổng hợp 3 ảnh sản phẩm này thành 1 ảnh catalog chuyên nghiệp');
form.append('model', 'gpt-image-1');
form.append('quality', 'high');
form.append('size', '1536x1024');
const response = await fetch('https://platform.beeknoee.com/v1/image/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-bee-xxxxxx' },
body: form,
});
console.log(await response.json());
Ví dụ 5: OpenAI Python SDK — Nhiều ảnh
# ⚠️ OpenAI SDK chỉ hỗ trợ 1 file trong client.images.edit()
# Để gửi nhiều ảnh, dùng requests trực tiếp (xem Ví dụ 2, 3 ở trên)
Giới hạn & Lưu ý
| Hạng mục | Giới hạn |
|---|---|
| Số ảnh tối đa | 16 ảnh / request |
| Kích thước mỗi ảnh | ≤ 4MB |
| Định dạng | PNG, JPEG |
| Models hỗ trợ | gpt-image-1, gpt-image-1.5, gpt-image-2, gpt-image-1-mini, chatgpt-image-latest, dall-e-2 |
| Mask | Có thể gửi kèm 1 mask (chỉ áp dụng cho ảnh đầu tiên) |
💡 Tip: Prompt nên mô tả rõ bạn muốn AI làm gì với các ảnh — kết hợp style, ghép nội dung, hay lấy từng phần cụ thể từ mỗi ảnh.
Lấy ảnh về — 2 kiểu phản hồi, phải xử lý cả hai
Đây là phần hay bị bỏ sót nhất. Không phải lúc nào gọi tạo ảnh cũng nhận được ảnh ngay.
Khi bạn gọi POST /v1/image/generations, phản hồi rơi vào một trong hai dạng — hãy luôn đọc trường status trước khi làm gì khác:
status | Nghĩa là | Bạn phải làm gì |
|---|---|---|
COMPLETED | Ảnh xong rồi, nằm sẵn trong data[] | Tải về, xong |
PROCESSING | Ảnh đang được tạo, mới chỉ có job_id | Hỏi lại cho tới khi xong (xem bên dưới) |
Vì sao có hai kiểu: mỗi model đi qua một nhà cung cấp khác nhau, có bên trả trong vài giây, có bên tạo nền rồi báo sau. Một số model (đặc biệt là ảnh 2K/4K và ảnh chất lượng cao) gần như luôn trả PROCESSING.
⚠️ Lỗi thường gặp nhất: code chỉ đọc
data[0].urlrồi báo lỗi khi nónull. Thực ra ảnh vẫn đang được tạo bình thường — bạn chỉ cần hỏi lại.
Phản hồi khi ảnh đang tạo
{
"job_id": "abc-123",
"status": "PROCESSING",
"data": [],
"cost_vnd": 1500,
"message": "Image is being generated. Check the status at GET /v1/image/generations/abc-123",
"estimated_time_seconds": 150
}
estimated_time_seconds chỉ là ước lượng (60–150 giây tuỳ model), không phải cam kết. Cửa sổ chờ tối đa là 60 phút — quá đó job mới bị đánh FAILED.
Bước 1 — Hỏi trạng thái
curl https://platform.beeknoee.com/v1/image/generations/abc-123 \
-H "Authorization: Bearer sk-bee-xxxxxx"
Khi ảnh ĐANG tạo — có sẵn thông tin để biết chờ đã lâu chưa:
{
"job_id": "abc-123",
"status": "PROCESSING",
"model": "bee/gpt-image-2",
"model_name": "GPT Image 2",
"supplier": "beeknoee",
"started_at": "2026-08-05T10:00:00.000Z",
"completed_at": null,
"elapsed_seconds": 45,
"estimated_time_seconds": 152,
"timeout_at": "2026-08-05T11:00:00.000Z",
"data": [],
"error_message": null
}
Đọc ra: đã chờ 45 giây · loại này thường mất khoảng 152 giây · quá 11:00 mà vẫn PROCESSING là bất thường.
| Trường | Ý nghĩa |
|---|---|
elapsed_seconds | Đã chờ bao nhiêu giây. Job xong rồi thì đây là thời gian tạo thật. |
estimated_time_seconds | Model này thường mất bao lâu — trung vị 50 ảnh gần nhất đã tạo xong trong 7 ngày. Số đo thật, tự điều chỉnh khi nhà cung cấp nhanh/chậm đi. Vắng mặt khi chưa đủ lịch sử. |
timeout_at | Mốc muộn nhất job còn được coi là đang chạy. Dùng để biết khi nào thôi hỏi lại. |
⚠️ Không có phần trăm hoàn thành, và cố ý không có. Nhà cung cấp chỉ báo 3 trạng thái (đang chạy / xong / hỏng), không hề gửi tiến độ.
elapsed_seconds / estimated_time_secondskhông phải phần trăm — ảnh có thể xong ở giây 30 hoặc giây 400. Vẽ thanh tiến trình từ hai số này thì nó sẽ chạy tới 99% rồi đứng im.
ℹ️
estimated_time_secondskhông có nghĩa là model đó chưa đủ ảnh hoàn tất để tính (model mới, hoặc ít người dùng). Không phải lỗi — cứ dựa vàoelapsed_secondsvàtimeout_at.
Khi ảnh đã xong:
{
"job_id": "abc-123",
"status": "COMPLETED",
"model": "bee/gpt-image-2",
"model_name": "GPT Image 2",
"supplier": "beeknoee",
"prompt": "a cinematic sunset over Ha Long Bay",
"revised_prompt": null,
"size": "1024x1024",
"quality": "high",
"style": null,
"n": 1,
"cost_vnd": 1500,
"started_at": "2026-08-05T10:00:00.000Z",
"completed_at": "2026-08-05T10:02:32.000Z",
"elapsed_seconds": 152,
"data": [
{ "url": "/v1/image/generations/abc-123/download?index=0" }
],
"error_message": null,
"cache_expires_at": "2026-08-08T10:00:00.000Z",
"created_at": "2026-08-05T10:00:00.000Z"
}
status có đúng 3 giá trị:
| Giá trị | Ý nghĩa |
|---|---|
PROCESSING | Đang tạo — hỏi lại sau |
COMPLETED | Xong — data[].url đã dùng được |
FAILED | Hỏng — lý do nằm ở error_message. Không bị trừ tiền. |
💰 Job
FAILEDkhông trừ ví. Tiền chỉ bị trừ khi job đạtCOMPLETED.
Bước 2 — Tải ảnh về
curl "https://platform.beeknoee.com/v1/image/generations/abc-123/download?index=0" \
-H "Authorization: Bearer sk-bee-xxxxxx" \
-o result.png
index chạy từ 0 tới n-1. Tạo 4 ảnh thì tải 4 lần với index=0,1,2,3.
Ví dụ đầy đủ: tạo ảnh rồi chờ lấy về (Python)
Đoạn này xử lý cả hai trường hợp, dùng được ngay:
import requests, time
BASE = "https://platform.beeknoee.com"
KEY = "sk-bee-xxxxxx"
H = {"Authorization": f"Bearer {KEY}"}
# 1. Yêu cầu tạo ảnh
r = requests.post(f"{BASE}/v1/image/generations", headers=H, json={
"model": "bee/gpt-image-2",
"prompt": "a cinematic sunset over Ha Long Bay",
"size": "1024x1024",
"quality": "high",
})
r.raise_for_status()
job = r.json()
# 2. Nếu chưa xong thì hỏi lại cho tới khi có kết quả
if job["status"] == "PROCESSING":
job_id = job["job_id"]
print(f"Đang tạo… job {job_id}")
deadline = time.time() + 3600 # cửa sổ tối đa 60 phút
while time.time() < deadline:
time.sleep(10) # 10 giây một lần là đủ, đừng hỏi dồn
job = requests.get(f"{BASE}/v1/image/generations/{job_id}", headers=H).json()
if job["status"] != "PROCESSING":
break
print(" … vẫn đang tạo")
# 3. Xử lý kết quả
if job["status"] == "FAILED":
raise SystemExit(f"Tạo ảnh hỏng: {job.get('error_message')}")
for i, _ in enumerate(job["data"]):
img = requests.get(f"{BASE}/v1/image/generations/{job['job_id']}/download?index={i}", headers=H)
open(f"anh-{i}.png", "wb").write(img.content)
print(f"Đã lưu anh-{i}.png")
print("Chi phí:", job["cost_vnd"], "đ")
Ví dụ tương đương (Node.js)
const BASE = 'https://platform.beeknoee.com';
const H = { Authorization: 'Bearer sk-bee-xxxxxx', 'Content-Type': 'application/json' };
const sleep = ms => new Promise(r => setTimeout(r, ms));
let job = await (await fetch(`${BASE}/v1/image/generations`, {
method: 'POST', headers: H,
body: JSON.stringify({ model: 'bee/gpt-image-2', prompt: 'a cinematic sunset', size: '1024x1024' }),
})).json();
const deadline = Date.now() + 3600_000; // 60 phút
while (job.status === 'PROCESSING' && Date.now() < deadline) {
await sleep(10_000);
job = await (await fetch(`${BASE}/v1/image/generations/${job.job_id}`, { headers: H })).json();
}
if (job.status === 'FAILED') throw new Error(job.error_message);
for (let i = 0; i < job.data.length; i++) {
const res = await fetch(`${BASE}/v1/image/generations/${job.job_id}/download?index=${i}`, { headers: H });
await require('fs').promises.writeFile(`anh-${i}.png`, Buffer.from(await res.arrayBuffer()));
}
Cách hỏi lại cho đúng
| Nên | Không nên |
|---|---|
| Hỏi 5–15 giây một lần | Hỏi mỗi giây — tốn hạn mức, không nhanh hơn |
Dừng khi quá timeout_at | Vòng lặp vô hạn |
Bắt cả FAILED | Chỉ chờ COMPLETED → treo vĩnh viễn khi job hỏng |
Hiện elapsed_seconds cho người dùng thấy | Vẽ thanh tiến trình phần trăm — không có dữ liệu thật để vẽ |
💡 Dùng dashboard thì không phải làm gì cả. Trang Sử dụng hiện ngay dòng "Đang tạo…" kèm thời gian đã chờ, và trang Thư viện tự hiện ảnh khi xong. Phần hỏi lại ở trên chỉ dành cho ai gọi API từ code của mình.
🔌 Nếu bạn dùng WebSocket: khi job kết thúc, hệ thống phát sự kiện
image:completed(hoặcimage:failed) tới đúng tài khoản đó — nhận được thì khỏi hỏi lại.
So sánh: Nên chọn model nào?
| Mục đích | Model gợi ý | Giá tham khảo |
|---|---|---|
| 🎨 Chất lượng cao nhất | gpt-image-2 (High) hoặc gpt-image-1 (High) | $0.167 - $0.270 |
| ⚡ Cân bằng giá/chất lượng | gpt-image-1.5 (Medium) hoặc gpt-image-2 (Medium) | $0.034 - $0.085 |
| 💰 Giá rẻ nhất | gpt-image-1-mini (Low) | $0.005 |
| 💰 Giá rẻ nhất (Google) | gemini-2.5-flash-image | xem bảng giá |
| 🖌️ Chỉnh sửa ảnh | gpt-image-2, gpt-image-1 hoặc dall-e-2 | $0.014 - $0.300 |
| 🍌 Sửa ảnh giữ nguyên tỉ lệ gốc | gemini-2.5-flash-image (rẻ) hoặc gemini-3-pro-image-preview (đẹp) | $0.039 - $0.240 |
| 📸 Ảnh mẫu / Reference | gpt-image-1 hoặc gpt-image-2 (qua /edits, không mask) | $0.014 - $0.300 |
| 🔄 Tạo biến thể | dall-e-2 (duy nhất) | $0.016 - $0.020 |
| 🖼️ Ảnh độ phân giải cao (2K/4K) | gemini-3.1-flash-image-preview hoặc gemini-3-pro-image-preview | $0.058 - $0.240 |
| 📐 Nhiều tỷ lệ khung hình | Google models (5 tỷ lệ × 3 resolution) | $0.039+ |
| 🔁 Luôn dùng phiên bản mới nhất | chatgpt-image-latest | $0.010 - $0.170 |
| 🌏 Text-to-Image giá rẻ | grok-imagine hoặc wan-2.7-image | $0.025 - $0.030 |
| 🎨 Chất lượng cao (non-OpenAI) | wan-2.7-image-pro hoặc grok-imagine-quality | $0.050 - $0.075 |
| 🖌️ I2I multi-reference | wan-2.7-image (9 ảnh) hoặc flux-2-pro (8 ảnh) | $0.030 - $0.050 |
Lưu ý quan trọng
- OpenAI URL hết hạn sau 1 giờ — Download ảnh ngay qua
/downloadendpoint - Google trả base64 — Không phải URL, dữ liệu ảnh nằm trong response
- Rate limits — Mỗi model có RPM (requests/phút) và RPD (requests/ngày) riêng
- Discount — Một số model có giảm giá theo plan (Free/Basic/Advanced+)
- Editing dùng
multipart/form-data(model OpenAI), riêng Gemini / Flux 2 / Seedream / Wan / Grok sửa ảnh bằng JSON +image_urls - Async — Hầu hết request sync < 15s. Nếu chậm hơn, hệ thống tự chuyển async + WebSocket notify
- Sửa ảnh bằng Gemini: bỏ trống
sizeđể giữ nguyên tỉ lệ ảnh gốc; chỉ truyềnsizekhi muốn đổi khung hình