> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tai-lieu-api/endpoints/image-generation.md). # Tạo hình ảnh Ước tính chi phí (chạy thử request): `POST /api/v1/image/estimate` Tạo hình ảnh bất đồng bộ: `POST /api/v1/image/generations/async` Kiểm tra trạng thái job bất đồng bộ: `GET /api/v1/image/generations/async/:generationId` ### Các trường request | Trường | Kiểu | Bắt buộc | Ràng buộc | Mô tả | | ---------------------------- | --------- | -------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | Có | Chuỗi | Mã định danh mô hình dành cho người dùng, lấy từ `/ai/models`. | | `content` | object\[] | Có | Mảng không rỗng | Nội dung request theo thứ tự. Hỗ trợ đầu vào văn bản và hình ảnh. | | `size` | string | Không | Phải có dạng `x` với số nguyên dương, ví dụ `1024x1024` | Kích thước hình ảnh đầu ra mong muốn. Nhà cung cấp có thể chuyển đổi giá trị này sang tỷ lệ khung hình hoặc mức kích thước riêng của họ. | | `numberOfImages` | integer | Không | Tối thiểu `1`, tối đa `15` | Số lượng hình ảnh đầu ra mong muốn. Hãy nêu thêm số lượng hình ảnh mong muốn trong prompt văn bản vì một số mô hình có thể trả về ít hình ảnh hơn yêu cầu. Số lượng thực tế khác nhau theo mô hình và nhà cung cấp. Các mô hình nhiều ảnh của BytePlus giới hạn tổng số ảnh ở `15`, tính cả ảnh tham chiếu và ảnh đầu ra mong muốn. | | `guidanceScale` | number | Không | Tối thiểu `1`, tối đa `10` | Mức độ bám sát prompt so với sự tự do sáng tạo. Giá trị cao hơn bám sát prompt hơn. Trường này không áp dụng chung: adapter hiện tại chuyển tiếp nó tới các mô hình hình ảnh BytePlus, và mức hỗ trợ của BytePlus tùy theo mô hình. Các mô hình không hỗ trợ có thể bỏ qua hoặc từ chối. | | `outputFormat` | string | Không | `png`, `jpeg` hoặc `webp` | Định dạng tệp đầu ra mong muốn. `webp` dành cho OpenAI gpt-image (Ofox `openai/*`); các mô hình hình ảnh BytePlus chỉ chấp nhận `png`/`jpeg`. Mức hỗ trợ của nhà cung cấp/mô hình hẹp hơn DTO, và các mô hình không hỗ trợ có thể bỏ qua hoặc từ chối giá trị này. | | `quality` | string | Không | `auto`, `high`, `medium` hoặc `low` | Chất lượng render. Chỉ dành cho OpenAI gpt-image (Ofox `openai/*`); bị bỏ qua với các nhà cung cấp/mô hình khác. Chất lượng cao hơn tốn nhiều chi phí hơn. | | `background` | string | Không | `transparent`, `opaque` hoặc `auto` | Độ trong suốt của nền. Chỉ dành cho OpenAI gpt-image (Ofox `openai/*`). `transparent` yêu cầu `outputFormat` là `png` hoặc `webp`. | | `outputCompression` | integer | Không | Tối thiểu `0`, tối đa `100` | Mức nén cho đầu ra `webp`/`jpeg`. Chỉ dành cho OpenAI gpt-image (Ofox `openai/*`). | | `watermark` | boolean | Không | Boolean | Có thêm watermark "AI generated" khi được hỗ trợ hay không. | | `optimizePromptOptions` | object | Không | Đối tượng | Các tùy chọn tối ưu prompt chỉ dành cho BytePlus. Hiện hỗ trợ `mode`; các adapter hình ảnh khác hiện tại không chuyển tiếp trường này. | | `optimizePromptOptions.mode` | string | Không | `standard` hoặc `fast` | Chế độ tối ưu prompt của BytePlus. `standard` ưu tiên chất lượng; `fast` ưu tiên độ trễ thấp hơn khi mô hình BytePlus được chọn hỗ trợ. | | `maxTokens` | integer | Không | Tối thiểu `1` | Số token tối đa được tạo cho các nhà cung cấp chấp nhận điều khiển token khi tạo hình ảnh. Một số mô hình hình ảnh không hỗ trợ trường này; tạo hình ảnh qua BytePlus sẽ loại bỏ trường này trước khi gửi request tới nhà cung cấp, còn tạo hình ảnh qua OpenRouter thì chuyển tiếp nó. | | `layerDecomposition` | boolean | Không | Boolean | Tách hình ảnh đầu vào thành một ảnh nền + tối đa 16 lớp. Chỉ dành cho BytePlus `dola-seedream-5-0-pro`. Xem phần Tách lớp bên dưới. | ### Tách lớp (`dola-seedream-5-0-pro`) Đặt `layerDecomposition: true` để tách một hình ảnh đầu vào thành ảnh nền và tối đa 16 lớp riêng (tổng cộng tối đa 17 ảnh đầu ra). Tính năng này chỉ khả dụng trên `dola-seedream-5-0-pro`. > **Bạn không thể chỉ định chính xác số ảnh đầu ra.** Ở chế độ này, `numberOfImages` được cố định ở `1` (xem các ràng buộc bên dưới). Mô hình tự quyết định số lớp dựa trên nội dung phát hiện trong ảnh, không dựa trên con số bạn đặt. Bạn chỉ có thể tác động gián tiếp qua prompt (xem ba cách bên dưới). Cách gần nhất để kiểm soát số lượng là nhắm mục tiêu cụ thể bằng tọa độ ``, vì mỗi vùng được chỉ định thường tạo thành một lớp. Giới hạn tối đa là 16 lớp cộng 1 ảnh nền, tức 17 ảnh; nếu mô hình phát hiện hơn 16 phần tử, một số thông tin về lớp có thể bị mất. **Các ràng buộc ở chế độ này:** * Chỉ nhận đúng một ảnh đầu vào (`content` phải chứa một part `imageUrl`/`imageBase64`/`imageAssetId`); request có nhiều ảnh sẽ bị từ chối. * Không chấp nhận `size`; hãy dùng `resolution` thay thế (`"1K"`, `"1.5K"`, `"2K"` hoặc `"auto"`, mặc định `"auto"`). `ratio` bị bỏ qua — tỷ lệ khung hình của ảnh nền luôn khớp với ảnh đầu vào. * `numberOfImages` phải được bỏ trống hoặc là `1`. * `outputFormat` chỉ áp dụng cho ảnh nền; mọi lớp luôn được trả về dạng `png`. * **Không hỗ trợ thành công một phần:** nếu tạo bất kỳ lớp nào thất bại, toàn bộ request sẽ thất bại. * Khi phát hiện trên 16 phần tử, một số thông tin lớp có thể bị mất. **Có ba cách chỉ định nội dung cần tách qua `prompt`/nội dung văn bản:** 1. Không có prompt — tự động phát hiện và tách mọi phần tử chính. 2. Mô tả bằng ngôn ngữ tự nhiên — mô tả ý định; bạn cũng có thể đánh dấu lên ảnh đầu vào (vẽ nguệch ngoạc, khoanh tròn) để hỗ trợ xác định vị trí. 3. Nhắm mục tiêu chính xác bằng tọa độ — dùng tag `` trong prompt với tọa độ đã chuẩn hóa. **Ghép các lớp:** `images[0]` là ảnh nền (`zIndex: 0`); các ảnh còn lại là lớp, sắp xếp theo `zIndex` tăng dần (từ dưới lên trên). Mỗi lớp được cắt sát theo phần tử, không có kích thước bằng toàn canvas. Trước khi ghép, hãy dùng `images[].boundingBox.absolute` (`[left, top, right, bottom]` tính bằng pixel, gốc ở góc trên bên trái ảnh nền) để đặt lớp vào đúng vị trí trong hệ tọa độ của ảnh nền. > **Chi phí:** mỗi ảnh trả về (ảnh nền và từng lớp) được tính như một ảnh đầu ra riêng. Một request tách lớp có thể trả về tối đa 17 ảnh, tương đương tối đa khoảng 17 lần chi phí của request tạo một ảnh thông thường. Không thể biết trước số lớp, nên `POST /image/estimate` không thể dự đoán chính xác chi phí của chế độ này. #### Ví dụ request tách lớp ``` POST /api/v1/image/generations/async ``` ```json { "model": "dola-seedream-5-0-pro", "content": [ { "type": "text", "text": "Precisely separate the image into layers." }, { "type": "imageUrl", "url": "https://your-accessible-url/input.png" } ], "resolution": "2K", "layerDecomposition": true, "watermark": true } ``` #### Ví dụ response tách lớp (rút gọn) ```json { "images": [ { "url": "https://...", "zIndex": 0 }, { "url": "https://...", "zIndex": 1, "boundingBox": { "absolute": [383, 120, 1655, 384], "normalized": [187, 59, 808, 188] }, "name": "Seedream title text", "description": "The 'Seedream' title in a large yellow serif font" }, { "url": "https://...", "zIndex": 7, "boundingBox": { "absolute": [698, 624, 1328, 2047], "normalized": [341, 305, 648, 1000] }, "name": "Scarlet macaw", "description": "A brightly colored scarlet macaw perched on a moss-covered branch" } ], "usage": { "generatedImages": 8, "totalTokens": 23107 } } ``` `images[0]` (`zIndex: 0`) là ảnh nền, không có `boundingBox`/`name`/`description`. Mỗi phần tử phía sau là một lớp. Dùng `boundingBox.absolute` để đặt lớp vào đúng vị trí trong hệ tọa độ của ảnh nền. ### Các content part của hình ảnh Mọi content part đều cần trường phân biệt `type`. | Loại | Trường | Mô tả | | ------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `text: string` | Văn bản prompt. Nhiều part văn bản sẽ được nối lại với các nhà cung cấp yêu cầu một prompt duy nhất. | | `imageUrl` | `url: string` | URL hình ảnh có thể truy cập công khai. Phải vượt qua bước kiểm tra URL. | | `imageBase64` | `data: string`, `mediaType?: string` | Dữ liệu hình ảnh base64 thô hoặc data URL đầy đủ. `mediaType` là bắt buộc với base64 thô và phải là một trong các MIME type hình ảnh được hỗ trợ. | Các MIME type hình ảnh được hỗ trợ: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`, `image/tiff`, `image/heic`, `image/heif`, `image/avif`. ### Ước tính chi phí Gửi đúng body dự định dùng cho endpoint tạo hình ảnh đến `POST /api/v1/image/estimate` để xem trước chi phí. Request ước tính không trừ credit và không lưu dữ liệu. > **Lưu ý:** Chi phí trả về chỉ là ước tính. Số tiền thực tế có thể khác và chỉ được xác định sau khi quá trình tạo hoàn tất. #### Ví dụ request ``` POST /api/v1/image/estimate ``` ```json { "model": "seedream-4-0", "content": [ { "type": "text", "text": "Create two clean product mockup images on a neutral background." } ], "size": "1024x1024", "numberOfImages": 2, "watermark": false } ``` #### Các trường response | Trường | Kiểu | Mô tả | | ------------------- | ------ | ------------------------------------------------------------------------------------------------ | | `estimatedUserCost` | number | Chi phí ước tính bằng USD. Khớp với số tiền sẽ được tạm giữ bởi `POST /image/generations/async`. | | `currency` | string | Luôn là `"USD"`. | #### Ví dụ response ```json { "data": { "estimatedUserCost": 0.12, "currency": "USD" }, "success": true, "status": 200 } ``` Nếu mức chi phí ước tính phù hợp, hãy gửi cùng body đó đến `POST /api/v1/image/generations/async` để tạo hình ảnh. ### Ví dụ request tạo hình ảnh ``` POST /api/v1/image/generations/async ``` ```json { "model": "seedream-4-0", "content": [ { "type": "text", "text": "Create two clean product mockup images on a neutral background." } ], "size": "1024x1024", "numberOfImages": 2, "watermark": false } ``` ### Các trường của ImageResult | Trường | Kiểu | Bắt buộc | Mô tả | | --------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `images` | object\[] | Có | Các hình ảnh đầu ra đã được tạo. | | `images[].url` | string | Không | URL của nhà cung cấp cho hình ảnh được tạo, khi trả về dưới dạng URL. URL của nhà cung cấp có thể hết hạn. | | `images[].downloadUrl` | string | Không | Link tải xuống R2 đã ký sẵn cho đầu ra được lưu trữ. URL này có thời hạn; hãy lấy lại thay vì lưu vĩnh viễn. | | `images[].assetId` | string | Không | ID tài nguyên của hình ảnh được lưu trữ. Dùng lại qua `imageAssetId` trong các request sau. | | `images[].zIndex` | integer | Không | Thứ tự xếp lớp: `0` cho ảnh nền, tăng dần lên trên. Chỉ với `layerDecomposition`. | | `images[].boundingBox` | object | Không | Vị trí của lớp này trong ảnh nền. Không có trên chính ảnh nền. Chỉ với `layerDecomposition`. | | `images[].boundingBox.absolute` | integer\[] | Không | `[left, top, right, bottom]` tính bằng pixel, gốc tọa độ `(0,0)` ở góc trên bên trái của ảnh nền. | | `images[].boundingBox.normalized` | integer\[] | Không | Giống `absolute`, được lượng tử hóa về `[0, 1000]` và cắt ở `1000`. | | `images[].name` | string | Không | Nhãn ngắn do mô hình tạo cho lớp này, ví dụ `"Seedream title text"`. Chỉ với `layerDecomposition`. | | `images[].description` | string | Không | Mô tả chi tiết hơn về lớp này (màu sắc, trạng thái, chất liệu). Chỉ với `layerDecomposition`. | | `usage` | object | Không | Mức sử dụng do nhà cung cấp báo cáo. | | `usage.generatedImages` | number | Không | Số lượng hình ảnh được nhà cung cấp tính. | | `usage.totalTokens` | number | Không | Tổng số token đã tiêu thụ, nếu được báo cáo. | | `usage.inputTokens` | number | Không | Token đầu vào văn bản cộng hình ảnh, nếu được báo cáo. | | `usage.outputTokens` | number | Không | Token đầu ra văn bản cộng hình ảnh, nếu được báo cáo. | | `usage.inputImageTokens` | number | Không | Phần token đầu vào thuộc về hình ảnh đầu vào. | | `usage.outputImageTokens` | number | Không | Phần token đầu ra thuộc về hình ảnh được tạo. | | `usage.usdCost` | number | Không | Chi phí USD do nhà cung cấp báo cáo, khi nhà cung cấp có báo cáo số liệu thanh toán. | ### Các trường trạng thái hình ảnh bất đồng bộ | Trường | Kiểu | Bắt buộc | Mô tả | | -------------- | ------ | -------- | ------------------------------------------------------------------------------- | | `status` | string | Có | Trạng thái hiện tại của job: `queued`, `processing`, `succeeded` hoặc `failed`. | | `generationId` | string | Có | ID generation được trả về khi job bất đồng bộ được chấp nhận. | | `result` | object | Không | `ImageResult`, có sau khi thành công. | | `error` | string | Không | Thông báo lỗi khi `status` là `failed`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tai-lieu-api/endpoints/image-generation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.