Hướng dẫn API v1 — IMG Studio

Tài liệu công khai cho người dùng và AI agent. Dùng API để tạo hoặc chỉnh sửa 1 ảnh mỗi request từ n8n, Make, script, OpenAI SDK hay ứng dụng ngoài. API video và webhook chưa được hỗ trợ.

• Trang HTML: https://imgstudio.site/docs/api
• Markdown cho AI agent: https://imgstudio.site/docs/api.md
• Base URL: https://imgstudio.site
• OpenAI-compatible base URL: https://imgstudio.site/api/v1

1. Bắt đầu nhanh cho AI agent

Nếu bạn là AI agent đang thiết lập kết nối thay người dùng, hãy làm theo thứ tự:

1. Yêu cầu người dùng tự tạo API key tại https://imgstudio.site/billing. Không yêu cầu họ gửi key vào chat công khai.
2. Lưu key trong biến môi trường hoặc secret manager, ví dụ IMG_STUDIO_API_KEY. Không ghi key vào source code, URL hay log.
3. Gọi GET /api/v1/providers hoặc GET /api/v1/models để lấy ID model thật. Không tự đoán ID từ tên hiển thị.
4. Tạo một Idempotency-Key mới cho mỗi tác vụ; khi retry cùng tác vụ phải giữ nguyên key đó.
5. Đặt timeout HTTP từ 300 giây vì quá trình tạo ảnh chạy đồng bộ.
6. Khi thành công, tải file ngay. Media thường chỉ được lưu khoảng 6 giờ; URL có chữ ký của API OpenAI-compatible hết hạn sau khoảng 10 phút.
7. Không tự retry lỗi 400, 401, 402, 403, 404, 409 hoặc 410. Với 202, chờ rồi gọi lại bằng cùng idempotency key. Với 429 hoặc lỗi 5xx tạm thời, retry có backoff và giữ nguyên key.

Có hai giao thức:

• API gốc: rõ nhất cho n8n, Make và HTTP script. Dùng provider_id, bắt buộc Idempotency-Key.
• OpenAI-compatible: phù hợp với OpenAI SDK hoặc công cụ cho nhập custom base URL. Dùng model; server ưu tiên Idempotency-Key, sau đó X-Request-ID, và tự sinh nếu cả hai đều thiếu.

2. Tạo API key và xác thực

1. Đăng nhập IMG Studio.
2. Vào Nạp tiền / API key tại https://imgstudio.site/billing.
3. Bấm Tạo API key và sao chép ngay; key chỉ hiện một lần, có dạng img_....
4. Có thể thu hồi key tại cùng trang. Mỗi tài khoản có tối đa 5 key đang hoạt động.

Mặc định chỉ admin hoặc tài khoản đã từng nạp tiền thật được tạo API key. Đây là gate chống lạm dụng lúc tạo key; quyền model và số dư vẫn được kiểm riêng khi gọi API.

Mọi request API phải có header:

Authorization: Bearer img_xxxxxxxx

Ví dụ dùng biến môi trường:

export IMG_STUDIO_API_KEY="img_xxxxxxxx"

3. API gốc

3.1. Lấy danh sách model

GET /api/v1/providers
Authorization: Bearer <API_KEY>

Response:

{
  "providers": [
    {
      "id": "uuid-provider",
      "name": "Tên model trên IMG Studio",
      "is_default": true,
      "supports_generate": true,
      "supports_edit": true,
      "supports_transparent_background_generate": true,
      "supports_transparent_background_edit": true,
      "max_edit_images": 3,
      "max_resolution": "4K"
    }
  ]
}

• Dùng id làm provider_id trong request tạo hoặc sửa ảnh.
• Chỉ gọi endpoint sửa ảnh khi supports_edit là true.
• Chỉ dùng background: "transparent" khi capability tương ứng với thao tác là true.
• Không gửi nhiều hơn max_edit_images ảnh nguồn.
• Danh sách chỉ gồm model mà tài khoản hiện được phép nhìn thấy; quyền sử dụng còn có thể phụ thuộc việc tài khoản đã nạp tiền.

3.2. Tạo ảnh

POST /api/v1/images/generate
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: <chuỗi duy nhất, tối đa 120 ký tự>

Body:

{
  "prompt": "a cat sitting on a windowsill, soft morning light",
  "provider_id": "uuid-provider",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "quality": "standard",
  "background": "opaque"
}

Response thành công 200:

{
  "id": "uuid-image",
  "status": "completed",
  "prompt": "...",
  "provider_name": "...",
  "model": "...",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "quality": "standard",
  "cost_vnd": 100,
  "balance_vnd": 9900,
  "url": "/api/v1/images/uuid-image/file",
  "created_at": "2026-01-01T00:00:00.000Z",
  "reused": false
}

url là đường dẫn tương đối. Ghép với https://imgstudio.site và gửi cùng Bearer header để tải file.

3.3. Chỉnh sửa ảnh

Endpoint này nhận multipart/form-data, không nhận JSON:

POST /api/v1/images/edit
Authorization: Bearer <API_KEY>
Idempotency-Key: <chuỗi duy nhất, tối đa 120 ký tự>
Content-Type: multipart/form-data; boundary=...

Tổng dung lượng toàn bộ ảnh nguồn tối đa 9.5MB mỗi request. Response thành công có cùng cấu trúc với endpoint tạo ảnh.

3.4. Lấy metadata và file ảnh

GET /api/v1/images/{id}
Authorization: Bearer <API_KEY>

GET /api/v1/images/{id}/file
Authorization: Bearer <API_KEY>

• Chỉ chủ ảnh hoặc admin được truy cập.
• File mặc định giữ định dạng đã lưu, thường là WebP.
• Thêm ?format=jpg để nhận JPEG.
• Hãy tải và lưu file vào nơi bền vững ngay sau khi tạo; media của user thường được tự xóa sau khoảng 6 giờ.

4. OpenAI-compatible API

Dùng base URL:

https://imgstudio.site/api/v1

Các endpoint:

GET /api/v1/models
POST /api/v1/images/generations
POST /api/v1/images/edits
Authorization: Bearer <API_KEY>

4.1. Danh sách model

GET /api/v1/models trả format OpenAI và thêm name, aliases:

{
  "object": "list",
  "data": [
    {
      "id": "uuid-provider",
      "name": "Tên model trên IMG Studio",
      "aliases": ["model-alias"],
      "object": "model",
      "created": 1767225600,
      "owned_by": "img-studio",
      "supports_transparent_background_generate": true,
      "supports_transparent_background_edit": true
    }
  ]
}

Dùng chính xác id hoặc một giá trị trong aliases làm model. name chỉ để hiển thị. Nếu aliases rỗng, dùng id.

4.2. Tạo ảnh

{
  "model": "uuid-provider",
  "prompt": "minimal product photo of a ceramic cup",
  "size": "1024x1024",
  "n": 1,
  "quality": "standard",
  "background": "opaque",
  "response_format": "url"
}

Response url trả URL tuyệt đối có chữ ký, không cần Bearer khi tải và hết hạn sau khoảng 10 phút. b64_json trả bytes ảnh dạng base64.

4.3. Chỉnh sửa ảnh

Dùng client.images.edit(...) hoặc POST /api/v1/images/edits với multipart/form-data:

• Ảnh nguồn: field image, image[] hoặc images.
• Các field còn lại: model, prompt, size, quality, background, response_format, n=1.
• background mặc định là opaque; chỉ dùng transparent khi supports_transparent_background_edit trong /models là true.
• mask chưa được hỗ trợ.
• Giới hạn model và số ảnh nguồn giống API gốc.

4.4. Idempotency

Nên gửi một header ổn định cho mọi lần retry cùng tác vụ:

Idempotency-Key: <request-id>

Hoặc:

X-Request-ID: <request-id>

Server ưu tiên Idempotency-Key. Nếu thiếu cả hai, server tự sinh ID để tương thích SDK, nhưng request gửi lại sau timeout có thể bị coi là tác vụ mới và trừ tiền thêm lần nữa. Nếu đổi background hoặc bất kỳ nội dung request nào để tạo một tác vụ khác, phải dùng key mới; retry cùng tác vụ phải giữ nguyên key cũ.

5. Ví dụ hoàn chỉnh

5.1. curl — API gốc

# Lấy model
curl -s https://imgstudio.site/api/v1/providers \
  -H "Authorization: Bearer $IMG_STUDIO_API_KEY"

# Tạo ảnh
curl -s https://imgstudio.site/api/v1/images/generate \
  -H "Authorization: Bearer $IMG_STUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-$(date +%s)" \
  -d '{
    "prompt": "minimal product photo of a ceramic cup",
    "provider_id": "PASTE_PROVIDER_ID",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

# Chỉnh sửa ảnh; curl tự đặt multipart boundary
curl -s https://imgstudio.site/api/v1/images/edit \
  -H "Authorization: Bearer $IMG_STUDIO_API_KEY" \
  -H "Idempotency-Key: edit-001" \
  -F "images=@input.png" \
  -F "prompt=đổi nền thành bãi biển hoàng hôn" \
  -F "provider_id=PASTE_PROVIDER_ID" \
  -F "resolution=1K"

5.2. Python — OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["IMG_STUDIO_API_KEY"],
    base_url="https://imgstudio.site/api/v1",
    timeout=300.0,
)

models = client.models.list()
model_id = models.data[0].id

result = client.images.generate(
    model=model_id,
    prompt="minimal product photo of a ceramic cup",
    size="1024x1024",
    n=1,
    response_format="b64_json",
    extra_headers={"Idempotency-Key": "python-create-001"},
)

with open("output.webp", "wb") as output:
    import base64
    output.write(base64.b64decode(result.data[0].b64_json))

5.3. JavaScript — OpenAI SDK

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.IMG_STUDIO_API_KEY,
  baseURL: "https://imgstudio.site/api/v1",
  timeout: 300_000,
});

const models = await client.models.list();
const model = models.data[0].id;
const result = await client.images.generate(
  {
    model,
    prompt: "minimal product photo of a ceramic cup",
    size: "1024x1024",
    n: 1,
    response_format: "b64_json",
  },
  { headers: { "Idempotency-Key": "js-create-001" } },
);

fs.writeFileSync("output.webp", Buffer.from(result.data[0].b64_json, "base64"));

6. n8n, Make và ứng dụng ngoài

n8n

1. Dùng node HTTP Request, method POST.
2. URL: https://imgstudio.site/api/v1/images/generate.
3. Header Authorization: Bearer img_....
4. Header Idempotency-Key: một ID ổn định của lần chạy, ví dụ {{$execution.id}}.
5. Body JSON gồm prompt, provider_id và các tùy chọn.
6. Đặt timeout 300 giây.
7. Node tiếp theo tải https://imgstudio.site{{ $json.url }} bằng cùng Bearer header và lưu binary ngay.

Với edit, chọn body Form-Data, đặt file binary vào field images; không tự đặt header Content-Type vì n8n cần tự thêm multipart boundary.

Make

Dùng module HTTP > Make a request với cùng URL và headers. Tạo ảnh dùng body type JSON; sửa ảnh dùng multipart/form-data. Đặt một ID của bundle hoặc execution vào Idempotency-Key, sau đó tải url trả về bằng request có Bearer header.

Photoshop và phần mềm desktop

Có thể tích hợp IMG Studio qua plugin hoặc script gọi HTTP API. Plugin nên lưu API key trong secure storage của ứng dụng, gọi danh sách model trước và tải file kết quả ngay. Việc cài plugin cụ thể phụ thuộc phiên bản Photoshop và công nghệ plugin mà khách đang dùng.

7. Mã lỗi và retry

Rate limit không phải một con số chung cho mọi model. Hệ thống chia lane theo nhóm model; lane thường là 3 tác vụ/phút/user, một số model nhanh có giới hạn cao hơn, còn một số model khan hiếm thấp hơn. Client nên chạy tuần tự hoặc concurrency thấp và xử lý 429 thay vì giả định RPM cố định.

8. Giá, đầu ra và bảo mật

• Giá phụ thuộc model, thao tác và độ phân giải; cost_vnd trong response thành công là số tiền thực tế của tác vụ.
• Đầu ra 4K cộng phụ phí cố định 150đ/ảnh. Hệ thống có thể hậu xử lý để đạt bậc đầu ra yêu cầu trong khi vẫn giữ request upstream trong giới hạn thật của model.
• Chỉnh sửa có thể có giá khác tạo ảnh.
• Provider hoặc hậu xử lý lỗi sau khi trừ tiền sẽ kích hoạt quy trình hoàn tiền; đọc message lỗi để biết đã hoàn hay đang cần admin kiểm tra.
• Không hỗ trợ video, batch nhiều ảnh đầu ra hoặc webhook async trong API v1 hiện tại.
• Không đưa API key vào frontend public, mobile bundle, URL query, source control, ảnh chụp màn hình hoặc log.
• Nếu key lộ, thu hồi ngay tại https://imgstudio.site/billing và tạo key mới.