Tổng quanMultimodal

Tạo ảnh

Trạm AI hỗ trợ tạo ảnh qua endpoint Chat Completions và Responses. Người dùng có thể xem model nào được hỗ trợ, khả năng của từng model và mức giá bằng cách lọc danh sách model theo image output.

Tìm model

Có nhiều cách để tìm model tạo ảnh:

Qua API

Dùng Public Models API để lấy danh sách model kèm thông tin chi tiết, sau đó lọc theo mode hoặc capabilities:

lines
$# Lấy danh sách tất cả model
$curl "https://api.staging.tram.ai.vn/public/models"
$
$# Tìm model tạo ảnh: lọc các model có mode = "image_generation"

Trên trang Models

Truy cập trang Models rồi lọc theo output modalities để tìm model có khả năng tạo ảnh. Hãy để ý những model liệt kê "image" trong output modalities.

Trong Chatroom

Khi dùng Chatroom, nhấp nút Image để tự động lọc và chọn model có khả năng tạo ảnh. Nếu chưa có model hỗ trợ ảnh nào đang hoạt động, người dùng sẽ được nhắc thêm một model.

Sử dụng API

Để tạo ảnh, gửi request đến endpoint /v1/chat/completions kèm parameter modalities. Giá trị tùy thuộc vào khả năng của model:

  • Model xuất cả text và ảnh (ví dụ: Gemini): dùng modalities: ["image", "text"]
  • Model chỉ xuất ảnh (ví dụ: Sourceful, Flux): dùng modalities: ["image"]

Tạo ảnh cơ bản

1import OpenAI from 'openai';
2
3const openai = new OpenAI({
4  baseURL: 'https://api.staging.tram.ai.vn/v1',
5  apiKey: '<TRAM_AI_API_KEY>',
6});
7
8const result = await openai.chat.completions.create({
9  model: 'google/gemini-2.5-flash-image',
10  messages: [
11    {
12      role: 'user',
13      content: 'Generate a beautiful sunset over mountains',
14    },
15  ],
16  modalities: ['image', 'text'],
17  stream: false,
18});
19
20// The generated image will be in the assistant message
21if (result.choices) {
22  const message = result.choices[0].message;
23  if (message.images) {
24    message.images.forEach((image, index) => {
25      const imageUrl = image.imageUrl.url; // Base64 data URL
26      console.log(`Generated image ${index + 1}: ${imageUrl.substring(0, 50)}...`);
27    });
28  }
29}

Tùy chọn cấu hình ảnh

Một số model tạo ảnh cho phép cấu hình thêm qua parameter image_config. Các tùy chọn dùng chung bên dưới — tỷ lệ khung hình (aspect ratio) và kích thước ảnh — đều hoạt động trên nhiều model ảnh. Những parameter dành riêng cho một provider cụ thể được tách thành các phần Recraft và Sourceful riêng ở phía dưới.

Tỷ lệ khung hình

Đặt image_config.aspect_ratio để yêu cầu một tỷ lệ khung hình cụ thể cho ảnh được tạo.

Các tỷ lệ khung hình được hỗ trợ:

  • 1:1 → 1024×1024 (default)
  • 2:3 → 832×1248
  • 3:2 → 1248×832
  • 3:4 → 864×1184
  • 4:3 → 1184×864
  • 4:5 → 896×1152
  • 5:4 → 1152×896
  • 9:16 → 768×1344
  • 16:9 → 1344×768
  • 21:9 → 1536×672

Tỷ lệ khung hình của Azure MAI Image (được hỗ trợ bởi microsoft/mai-image-2.5):

  • 1:1 → 1024×1024 (default)
  • 4:3 → 1024×768
  • 3:4 → 768×1024
  • 16:9 → 1365×768
  • 9:16 → 768×1365
  • 3:2 → 1152×768
  • 2:3 → 768×1152

Tỷ lệ khung hình mở rộng (chỉ được hỗ trợ bởi google/gemini-3.1-flash-image-preview):

  • 1:4 → Định dạng cao và hẹp, lý tưởng cho carousel cuộn và các phần tử UI dọc
  • 4:1 → Định dạng rộng và thấp, dành cho hero banner và bố cục ngang
  • 1:8 → Định dạng siêu cao, dành cho phần đầu thông báo và các không gian dọc hẹp
  • 8:1 → Định dạng siêu rộng, dành cho banner khổ rộng và bố cục toàn cảnh

Kích thước ảnh

Đặt image_config.image_size để kiểm soát độ phân giải của ảnh được tạo.

Các kích thước được hỗ trợ:

  • 1K → Độ phân giải chuẩn (mặc định)
  • 2K → Độ phân giải cao hơn
  • 4K → Độ phân giải cao nhất
  • 0.5K → Độ phân giải thấp hơn, tối ưu cho hiệu quả (chỉ được hỗ trợ bởi google/gemini-3.1-flash-image-preview)

Người dùng có thể kết hợp aspect_ratio và image_size trong cùng một request:

1import requests
2import json
3
4url = "https://api.staging.tram.ai.vn/v1/chat/completions"
5headers = {
6    "Authorization": f"Bearer {API_KEY_REF}",
7    "Content-Type": "application/json"
8}
9
10payload = {
11    "model": "google/gemini-3-pro-image-preview",
12    "messages": [
13        {
14            "role": "user",
15            "content": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"
16        }
17    ],
18    "modalities": ["image", "text"],
19    "image_config": {
20        "aspect_ratio": "16:9",
21        "image_size": "4K"
22    }
23}
24
25response = requests.post(url, headers=headers, json=payload)
26result = response.json()
27
28if result.get("choices"):
29    message = result["choices"][0]["message"]
30    if message.get("images"):
31        for image in message["images"]:
32            image_url = image["image_url"]["url"]
33            print(f"Generated image: {image_url[:50]}...")

Tùy chọn ảnh của Recraft

Các parameter trong phần này chỉ được hỗ trợ bởi model Recraft. Khi một parameter chỉ áp dụng cho một phiên bản Recraft cụ thể (ví dụ V3 nhưng không phải V4), điều đó sẽ được ghi chú ngay tại parameter đó.

Strength

Đặt image_config.strength để kiểm soát mức độ khác biệt giữa ảnh đầu ra và ảnh đầu vào khi tạo ảnh từ ảnh (image-to-image). Parameter này chỉ áp dụng khi có ảnh đầu vào trong messages, và được hỗ trợ bởi tất cả các model Recraft (recraft/recraft-v3, recraft/recraft-v4 và recraft/recraft-v4-pro).

  • Khoảng giá trị: 0.0 đến 1.0
  • Mặc định: 0.2
  • Giá trị càng thấp thì đầu ra càng bám sát ảnh đầu vào; giá trị càng cao thì model càng được sáng tạo, sai lệch nhiều hơn.

Ví dụ:

lines
1{
2  "image_config": {
3    "strength": 0.7
4  }
5}

Text Layout (chỉ Recraft V3)

Dùng image_config.text_layout để đặt văn bản tại những vị trí cụ thể trên ảnh được tạo. Mỗi mục chỉ định văn bản cần render và một bounding box xác định bởi bốn điểm góc theo tọa độ chuẩn hóa (0 đến 1). Parameter này chỉ được Recraft V3 (recraft/recraft-v3) hỗ trợ, cho cả request text-to-image và image-to-image. Recraft V4 và V4 Pro không hỗ trợ text_layout.

Mỗi mục text layout là một object gồm:

  • text (bắt buộc): chuỗi văn bản cần render
  • bbox (bắt buộc): mảng gồm 4 cặp tọa độ [x, y] xác định các góc của bounding box (trên-trái, trên-phải, dưới-phải, dưới-trái), với giá trị từ 0 đến 1

Ví dụ:

lines
1{
2  "image_config": {
3    "text_layout": [
4      {
5        "text": "Hello",
6        "bbox": [[0.3, 0.45], [0.6, 0.45], [0.6, 0.55], [0.3, 0.55]]
7      },
8      {
9        "text": "World",
10        "bbox": [[0.35, 0.6], [0.65, 0.6], [0.65, 0.7], [0.35, 0.7]]
11      }
12    ]
13  }
14}

Style (chỉ Recraft V3)

Dùng image_config.style để áp dụng một phong cách nghệ thuật cụ thể cho ảnh được tạo. Parameter này chỉ được Recraft V3 (recraft/recraft-v3) hỗ trợ. Recraft V4 và V4 Pro không hỗ trợ style.

Xem danh sách đầy đủ các style khả dụng trong tài liệu của Recraft. Lưu ý rằng style vector không được hỗ trợ.

Ví dụ:

lines
1{
2  "image_config": {
3    "style": "Photorealism"
4  }
5}

RGB Colors

Dùng image_config.rgb_colors để chỉ định một bảng màu chi phối ảnh được tạo. Mỗi màu là một mảng [r, g, b] gồm ba số nguyên (0 đến 255). Tùy chọn này được hỗ trợ bởi tất cả các model Recraft (recraft/recraft-v3, recraft/recraft-v4 và recraft/recraft-v4-pro) cho cả request text-to-image và image-to-image.

Ví dụ:

lines
1{
2  "image_config": {
3    "rgb_colors": [
4      [255, 0, 0],
5      [0, 128, 0]
6    ]
7  }
8}

Background RGB Color

Dùng image_config.background_rgb_color để đặt một màu nền cụ thể cho ảnh được tạo. Giá trị là một mảng [r, g, b] gồm ba số nguyên (0 đến 255). Tùy chọn này được hỗ trợ bởi tất cả các model Recraft (recraft/recraft-v3, recraft/recraft-v4 và recraft/recraft-v4-pro) cho cả request text-to-image và image-to-image.

Ví dụ:

lines
1{
2  "image_config": {
3    "background_rgb_color": [0, 0, 255]
4  }
5}

Người dùng cũng có thể kết hợp rgb_colors và background_rgb_color trong cùng một request:

lines
1{
2  "image_config": {
3    "rgb_colors": [[255, 0, 0]],
4    "background_rgb_color": [255, 255, 255]
5  }
6}

Tùy chọn ảnh của Sourceful

Các parameter trong phần này chỉ được hỗ trợ bởi model Sourceful. Mỗi parameter đều ghi chú phiên bản Sourceful (V2 hoặc V2.5) hỗ trợ nó.

Font Inputs (Riverflow V2 trở lên)

Dùng image_config.font_inputs để render văn bản tùy chỉnh với những font cụ thể trong ảnh được tạo. Để có kết quả tốt nhất, văn bản cần render cũng nên được đưa vào trong prompt. Tùy chọn này được hỗ trợ bởi Sourceful Riverflow V2 trở lên — sourceful/riverflow-v2-fast, sourceful/riverflow-v2-pro, sourceful/riverflow-v2.5-fast và sourceful/riverflow-v2.5-pro.

Mỗi font input là một object gồm:

  • font_url (bắt buộc): URL đến file font
  • text (bắt buộc): văn bản cần render với font đó

Giới hạn:

  • Tối đa 2 font input mỗi request
  • Chi phí bổ sung: $0.03 mỗi font input

Ví dụ:

lines
1{
2  "image_config": {
3    "font_inputs": [
4      {
5        "font_url": "https://example.com/fonts/custom-font.ttf",
6        "text": "Hello World"
7      }
8    ]
9  }
10}

Mẹo để có kết quả tốt nhất:

  • Đưa văn bản vào prompt cùng với chi tiết về tên font, màu sắc, kích thước và vị trí
  • Parameter text nên khớp chính xác với nội dung trong prompt — tránh thêm từ ngữ thừa hoặc dấu ngoặc kép
  • Dùng dấu xuống dòng hoặc dấu cách đôi để tách tiêu đề chính và tiêu đề phụ khi dùng cùng một font
  • Hoạt động tốt nhất với tiêu đề chính và tiêu đề phụ ngắn gọn, rõ ràng

Super Resolution References (chỉ Riverflow V2)

Dùng image_config.super_resolution_references để cải thiện các phần tử chất lượng thấp trong ảnh đầu vào bằng những ảnh tham chiếu chất lượng cao. Ảnh đầu ra sẽ khớp với kích thước ảnh đầu vào, vì vậy hãy dùng ảnh đầu vào lớn hơn để có kết quả tốt hơn. Tùy chọn này được hỗ trợ bởi các model Sourceful V2 (sourceful/riverflow-v2-fast và sourceful/riverflow-v2-pro) khi tạo ảnh image-to-image (tức là khi có ảnh đầu vào trong messages).

Giới hạn:

  • Tối đa 4 URL tham chiếu mỗi request
  • Chỉ hoạt động với request image-to-image (bị bỏ qua khi không có ảnh trong messages)
  • Chi phí bổ sung: $0.20 mỗi tham chiếu

Ví dụ:

lines
1{
2  "image_config": {
3    "super_resolution_references": [
4      "https://example.com/reference1.jpg",
5      "https://example.com/reference2.jpg"
6    ]
7  }
8}

Mẹo để có kết quả tốt nhất:

  • Cung cấp ảnh đầu vào mà trong đó các phần tử cần cải thiện đã xuất hiện sẵn nhưng còn chất lượng thấp
  • Dùng ảnh đầu vào lớn hơn để có chất lượng đầu ra tốt hơn (đầu ra khớp với kích thước đầu vào)
  • Dùng ảnh tham chiếu chất lượng cao thể hiện rõ mong muốn các phần tử sau khi cải thiện trông như thế nào

Scoring Prompt (chỉ Riverflow V2.5)

Dùng image_config.scoring_prompt để đưa cho model một hướng dẫn dạng tự do, để model dựa vào đó đánh giá và tinh chỉnh đầu ra của chính nó trong quá trình tạo ảnh. Tùy chọn này được hỗ trợ bởi các model Sourceful V2.5 (sourceful/riverflow-v2.5-fast và sourceful/riverflow-v2.5-pro).

Ví dụ:

lines
1{
2  "image_config": {
3    "scoring_prompt": "Prefer realistic materials, crisp product edges, and even studio lighting."
4  }
5}

Scoring Rubric (chỉ Riverflow V2.5)

Dùng image_config.scoring_rubric để cung cấp một tập hợp có cấu trúc gồm các tiêu chí có trọng số, để model dựa vào đó chấm điểm đầu ra của nó. Đây là phần bổ trợ có cấu trúc cho scoring_prompt — hai parameter này độc lập với nhau và có thể được dùng chung trong cùng một request (rubric để chấm điểm theo tiêu chí có trọng số, prompt để bổ sung hướng dẫn dạng tự do). Tùy chọn này được hỗ trợ bởi các model Sourceful V2.5 (sourceful/riverflow-v2.5-fast và sourceful/riverflow-v2.5-pro).

Mỗi mục rubric là một object gồm:

  • key (bắt buộc): định danh duy nhất, máy đọc được cho tiêu chí này
  • label (bắt buộc): tên dạng người đọc được
  • description (bắt buộc): tiêu chí này đánh giá điều gì
  • weight (bắt buộc): mức độ quan trọng tương đối, là một số dương
  • passing_score (tùy chọn): điểm tối thiểu có thể chấp nhận
  • score_guidance (tùy chọn): mảng các mốc neo dạng { "score": number, "description": string }

Giới hạn:

  • 1 đến 8 tiêu chí mỗi request

Ví dụ:

expandable lines
1{
2  "image_config": {
3    "scoring_rubric": [
4      {
5        "key": "lighting",
6        "label": "Lighting quality",
7        "description": "Even, professional studio lighting with no blown highlights.",
8        "weight": 2,
9        "passing_score": 7,
10        "score_guidance": [
11          { "score": 10, "description": "Flawless, even studio lighting." },
12          { "score": 5, "description": "Acceptable but uneven lighting." }
13        ]
14      },
15      {
16        "key": "edges",
17        "label": "Edge sharpness",
18        "description": "Crisp, clean product edges without halos.",
19        "weight": 1
20      }
21    ]
22  }
23}

Background Mode and Color (chỉ Riverflow V2.5)

Dùng image_config.background_mode để kiểm soát cách xử lý nền của ảnh được tạo, và image_config.background_hex_color để đặt màu tô cho nền đặc. Hai tùy chọn này được hỗ trợ bởi các model Sourceful V2.5 (sourceful/riverflow-v2.5-fast và sourceful/riverflow-v2.5-pro).

  • background_mode: nhận một trong các giá trị original (mặc định — giữ nguyên nền được tạo), transparent (xóa nền), hoặc solid (ghép lên một màu phẳng).
  • background_hex_color: một chuỗi hex #RRGGBB, bắt buộc khi background_mode là solid.

Hành vi:

  • Nếu chỉ truyền background_hex_color (không kèm background_mode), giá trị này sẽ được xử lý như solid với màu đó.
  • background_hex_color luôn được kiểm tra tính hợp lệ nhưng sẽ bị bỏ qua với chế độ original và transparent — một chuỗi hex không hợp lệ luôn trả về lỗi 400, bất kể đang ở chế độ nào.

Ví dụ (màu đặc):

lines
1{
2  "image_config": {
3    "background_mode": "solid",
4    "background_hex_color": "#f6f1e8"
5  }
6}

Ví dụ (trong suốt):

lines
1{
2  "image_config": {
3    "background_mode": "transparent"
4  }
5}

Recraft dùng background_rgb_color (một mảng [r, g, b]) để đặt màu nền đặc, còn Sourceful V2.5 thì dùng background_mode đi kèm background_hex_color.

Tạo ảnh với streaming

Tạo ảnh cũng hoạt động với response dạng streaming:

1import requests
2import json
3
4url = "https://api.staging.tram.ai.vn/v1/chat/completions"
5headers = {
6    "Authorization": f"Bearer {API_KEY_REF}",
7    "Content-Type": "application/json"
8}
9
10payload = {
11    "model": "google/gemini-2.5-flash-image",
12    "messages": [
13        {
14            "role": "user",
15            "content": "Create an image of a futuristic city"
16        }
17    ],
18    "modalities": ["image", "text"],
19    "stream": True
20}
21
22response = requests.post(url, headers=headers, json=payload, stream=True)
23
24for line in response.iter_lines():
25    if line:
26        line = line.decode('utf-8')
27        if line.startswith('data: '):
28            data = line[6:]
29            if data != '[DONE]':
30                try:
31                    chunk = json.loads(data)
32                    if chunk.get("choices"):
33                        delta = chunk["choices"][0].get("delta", {})
34                        if delta.get("images"):
35                            for image in delta["images"]:
36                                print(f"Generated image: {image['image_url']['url'][:50]}...")
37                except json.JSONDecodeError:
38                    continue

Định dạng response

Khi tạo ảnh, tin nhắn của assistant sẽ có thêm trường images chứa những ảnh được tạo ra:

lines
1{
2  "choices": [
3    {
4      "message": {
5        "role": "assistant",
6        "content": "I've generated a beautiful sunset image for you.",
7        "images": [
8          {
9            "type": "image_url",
10            "image_url": {
11              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
12            }
13          }
14        ]
15      }
16    }
17  ]
18}

Định dạng ảnh

  • Định dạng: ảnh được trả về dưới dạng data URL mã hóa base64
  • Loại: thường là định dạng PNG (data:image/png;base64,)
  • Nhiều ảnh: một số model có thể tạo nhiều ảnh trong cùng một response
  • Kích thước: kích thước ảnh khác nhau tùy theo khả năng của model

Tính tương thích của model

Không phải model nào cũng hỗ trợ tạo ảnh. Để dùng tính năng này:

  1. Kiểm tra khả năng model: đảm bảo model có mode: "image_generation" (kiểm tra qua Public Models API)
  2. Đặt parameter Modalities: dùng ["image", "text"] cho model xuất cả hai, hoặc ["image"] cho model chỉ xuất ảnh
  3. Dùng model tương thích: ví dụ:
    • google/gemini-3.1-flash-image-preview (hỗ trợ tỷ lệ khung hình mở rộng và độ phân giải 0.5K)
    • google/gemini-2.5-flash-image
    • black-forest-labs/flux.2-pro
    • black-forest-labs/flux.2-flex
    • sourceful/riverflow-v2-standard-preview
    • Cùng các model khác có khả năng tạo ảnh

Thực hành tốt nhất

  • Prompt rõ ràng: mô tả càng chi tiết thì chất lượng ảnh càng tốt
  • Chọn model: ưu tiên những model được thiết kế riêng cho việc tạo ảnh
  • Xử lý lỗi: kiểm tra trường images trong response trước khi xử lý tiếp
  • Rate limit: tạo ảnh có thể có rate limit khác với tạo text
  • Lưu trữ: cân nhắc trước cách xử lý và lưu trữ dữ liệu ảnh base64

Khắc phục sự cố

Không có ảnh trong response?

  • Xác minh model có hỗ trợ tạo ảnh (kiểm tra mode: "image_generation" qua Public Models API)
  • Đảm bảo đã đặt parameter modalities đúng cách: ["image", "text"] cho model xuất cả hai, hoặc ["image"] cho model chỉ xuất ảnh
  • Kiểm tra xem prompt có thực sự đang yêu cầu tạo ảnh không

Không tìm thấy model?

  • Dùng trang Models để tìm những model tạo ảnh khả dụng
  • Lọc theo output modalities để xem các model tương thích