---
name: solart
description: Tạo ảnh và video AI bằng tài khoản Solart (https://solart.app) qua REST API. Dùng khi người dùng muốn tạo ảnh, chỉnh sửa ảnh theo yêu cầu, ghép ảnh tham chiếu, làm ảnh sản phẩm, chân dung, minh hoạ hoặc video ngắn từ mô tả hay từ ảnh, xem số dư credit hoặc lịch sử tạo trên Solart.
---

# Solart: tạo ảnh và video AI

Solart gọi các model AI (GPT Image, Gemini, Veo, Kling...) và trừ credit của người dùng cho mỗi lượt tạo. Lượt lỗi được hoàn credit tự động.

## Chuẩn bị

- Cần API key dạng `slr_...` trong biến môi trường `SOLART_API_KEY`. Chưa có thì nhờ người dùng tạo tại https://solart.app/account/api-keys.
- Nếu đã có MCP server `solart` (tool `generate`, `list_models`...), ưu tiên dùng tool MCP thay cho gọi HTTP.
- Mọi request gửi header `Authorization: Bearer $SOLART_API_KEY`. Base URL: `https://solart.app/api/v1`.

## Quy trình

1. Kiểm tra số dư: `GET /me` trả `creditBalance`.
2. Chọn model: `GET /models?type=image` (hoặc `video`). Mỗi model có `credits` (ảnh: credit mỗi ảnh; video: xem `durations` và `durationCredits` cùng thứ tự), `aspectRatios`, `resolutions` (kèm credit theo độ phân giải), `maxReferenceImages`, `firstFrame`, `lastFrame`. Bỏ trống `model` để dùng model mặc định.
3. Ảnh tham chiếu (tuỳ chọn): `POST /uploads` nhận multipart trường `file`, hoặc JSON `{"url": "https://..."}` hay `{"data": "<base64>"}`. Trả về `id` dùng trong `referenceIds`, `firstFrameId`, `lastFrameId`.
4. Tạo: `POST /generations?wait=55`. Với `wait`, request giữ tối đa 55 giây và trả luôn kết quả nếu đã xong.
5. Nếu `status` vẫn là `queued` hoặc `processing`: gọi `GET /generations/{id}?wait=55` lặp lại tới khi `succeeded` hoặc `failed`. Ảnh thường xong trong 10-60 giây, video vài phút.
6. Kết quả nằm ở `outputs[].url` (xem) và `outputs[].downloadUrl` (tải về). File bị xoá sau `filesExpireAt` (khoảng 3 ngày), hãy tải về nếu cần giữ.

## Ví dụ

Tự viết prompt:

```bash
curl -s -X POST "https://solart.app/api/v1/generations?wait=55" \
  -H "Authorization: Bearer $SOLART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"custom","type":"image","prompt":"Cô gái mặc áo dài trắng đứng bên hồ sen lúc bình minh, ảnh chụp film","params":{"aspectRatio":"3:4"}}'
```

Sửa ảnh có sẵn theo yêu cầu:

```bash
ID=$(curl -s -X POST "https://solart.app/api/v1/uploads" -H "Authorization: Bearer $SOLART_API_KEY" -F "file=@photo.jpg" | jq -r .id)
curl -s -X POST "https://solart.app/api/v1/generations?wait=55" \
  -H "Authorization: Bearer $SOLART_API_KEY" -H "Content-Type: application/json" \
  -d "{\"mode\":\"custom\",\"type\":\"image\",\"prompt\":\"Đổi nền sang bãi biển lúc hoàng hôn, giữ nguyên khuôn mặt\",\"referenceIds\":[\"$ID\"]}"
```

Dùng mẫu viết sẵn: `GET /templates` lấy `slug`, `GET /templates/{slug}` xem `variables`, rồi gửi `{"mode":"template","templateSlug":"...","inputs":{"<key>":"<giá trị>"}}`. Biến kiểu `select` phải dùng đúng `value` của một lựa chọn trong `options`.

Video từ ảnh: tải ảnh lên, gửi `{"mode":"custom","type":"video","prompt":"...","firstFrameId":"<id>","params":{"durationSeconds":5}}` với model có `firstFrame: true`.

## Lỗi thường gặp

- 401 `invalid_api_key`: key sai hoặc đã thu hồi.
- 402: không đủ credit, báo người dùng nạp tại https://solart.app/pricing.
- 422: tham số không hợp lệ (tỉ lệ, độ phân giải, thời lượng không có trong model, thiếu biến của mẫu). Đọc `error` và `details`, sửa rồi gửi lại.
- 429: vượt giới hạn tần suất hoặc số lượt đang chờ, đợi theo header `Retry-After`.
- `status: failed`: xem `error`, credit đã được hoàn (`refunded: true`).

## Lưu ý

- Luôn báo trước số credit sẽ dùng nếu người dùng chưa đồng ý chi phí, nhất là với video.
- Không tạo hàng loạt khi người dùng chỉ cần một kết quả.
- Đặc tả đầy đủ: https://solart.app/api/v1/openapi.json. Tài liệu: https://solart.app/developers.