Dành cho nhà phát triển

Tài liệu API

Gọi các model AI (ảnh, video, giọng nói, âm nhạc...) bằng tên model chuẩn và tham số quen thuộc. Tiền trừ vào số dư tài khoản (VND) giống hệt khi dùng trên web.

Xác thực

Mọi yêu cầu gửi tới địa chỉ gốc dưới đây. Tạo API key ở trang API cho nhà phát triển (cần đăng nhập), rồi gửi kèm trong header X-API-Key hoặc Authorization: Bearer.

https://moimedia.net/api
curl https://moimedia.net/api/v1/models \
  -H "X-API-Key: cmsnt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  • Key chỉ hiện đầy đủ một lần khi tạo. Mất key thì thu hồi và tạo key mới.
  • Chỉ dùng key ở máy chủ của bạn, không nhúng vào mã chạy trên trình duyệt hay ứng dụng di động.
  • Dữ liệu gửi và nhận ở dạng JSON (trừ API tải file dùng multipart/form-data).

Luồng gọi API

  1. Chọn model: GET /v1/models — mỗi model có mã (id) như gpt-image-2, kling-2.6, seedream-5.0 và danh sách tham số (params).
  2. Gửi Input: POST /v1/generations với { "model": "...", ...tham số } — hệ thống trừ tiền và trả về id tác vụ.
  3. Nhận Output: GET /v1/generations/{id} mỗi 5–10 giây tới khi status là succeeded, rồi lấy link file trong output.files.

Mã model theo tên model gốc. Cùng một model có nhiều chế độ thì thêm tác vụ phía sau, vd kling-2.6/first-last-frame (ảnh đầu + ảnh cuối). Tham số đặt tên snake_case theo quy ước phổ biến: prompt, aspect_ratio, resolution, duration, image_url, voice...

Danh mục model

GET/v1/models?output=imageKhông cần key

Danh sách model đang mở bán. Lọc tuỳ chọn theo output (image | video | audio | text) hoặc type (nhóm menu).

GET/v1/models/{id}Không cần key

Chi tiết một model với đầy đủ tham số đầu vào (danh sách lựa chọn dài như giọng đọc chỉ có ở API này).

{
  "id": "gemini-image",
  "object": "model",
  "name": "Gemini Image · 2K/4K, khuyên dùng",
  "type": "image",
  "output": "image",       // image | video | audio | text
  "pricing": { "mode": "fixed", "base": 1500, "per_unit": 0, "unit": null, "min": 0, "currency": "VND" },
  "params": [
    { "name": "prompt", "type": "string", "required": true, "description": "Mô tả", "max": 20000 },
    { "name": "aspect_ratio", "type": "enum", "required": false, "default": "1:1",
      "options": [{ "value": "1:1", "label": "1:1" }, { "value": "16:9", "label": "16:9" }] },
    { "name": "image_url", "type": "file_url", "file_type": "image", "required": false, "description": "Ảnh mẫu" }
  ]
}

Ý nghĩa các trường của params:

TrườngÝ nghĩa
typestring · integer · number · boolean · enum · file_url (URL file, xem phần tải file)
required / defaultBắt buộc hay không, giá trị dùng khi bỏ trống.
optionsGiá trị hợp lệ của enum (value gửi lên API, label là nhãn hiển thị).
min / maxGiới hạn số; với string là độ dài tối đa.
multiple / max_filesTham số file nhận mảng nhiều URL.
only_ifTham số chỉ có hiệu lực khi tham số khác có giá trị nằm trong danh sách.
options_byLựa chọn thay đổi theo giá trị tham số khác.
combinationsduration và resolution chỉ nhận các tổ hợp liệt kê ở đây.

Input: tạo tác vụ

POST/v1/generations

Body là JSON phẳng: model + các tham số của model đó ở cùng cấp. Tham số sai tên hoặc không có trong params bị từ chối (400) để bạn phát hiện lỗi sớm.

curl -X POST https://moimedia.net/api/v1/generations \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
  "model": "gemini-image",
  "prompt": "Một chú mèo phi hành gia",
  "size": "1:1",
  "n": "1"
}'

Kết quả trả ngay đối tượng generation (status queued / processing). Tiền được trừ lúc tạo, lỗi thì tự hoàn lại.

Output: kết quả

GET/v1/generations/{id}

Nhận id (uuid) hoặc mã tác vụ (code). Hỏi lại mỗi 5–10 giây cho tới khi status là succeeded, failed hoặc cancelled.

{
  "id": "3f1c...-uuid",
  "object": "generation",
  "code": "T8KQ2M4X",
  "model": "gemini-image",
  "status": "succeeded",
  "progress": 100,
  "cost": 1500,                 // số tiền VND đã trừ
  "currency": "VND",
  "refunded": false,
  "output": {
    "type": "image",
    "files": [{ "url": "https://moimedia.net/uploads/ai/outputs/....png", "type": "image", "name": "image.png" }],
    "text": null                // chỉ có với model trả văn bản
  },
  "error": null,
  "created_at": "2026-10-30T08:00:00.000Z",
  "completed_at": "2026-10-30T08:00:41.000Z"
}
statusÝ nghĩa
queuedĐã nhận, đang gửi sang máy chủ AI
processingĐang xử lý; progress là phần trăm hoàn thành (nếu có)
succeededXong; kết quả nằm trong output.files (và output.text)
failedLỗi; lý do ở error, tiền tự hoàn lại vào số dư (refunded = true)
cancelledĐã huỷ, tiền được hoàn lại vào số dư

Nên tải file kết quả về hệ thống của bạn: file trên máy chủ có thể được dọn sau một thời gian.

Báo giá

POST/v1/generations/estimate

Cùng body với tạo tác vụ, chỉ tính số tiền (VND) sẽ trừ, không chạy và không trừ tiền.

# => { "object": "estimate", "model": "gemini-image", "cost": 1500, "currency": "VND" }

Tải file đầu vào

Tham số kiểu file_url (vd image_url, video_url, reference_image_urls) nhận một trong hai:

  • Link công khai http(s) tới file (ảnh PNG/JPG/WEBP, video MP4/MOV/WEBM, âm thanh MP3/WAV/M4A) — máy chủ tự tải về, tối đa 10 file mỗi lần gọi.
  • URL trả về từ API tải file dưới đây (file nằm trên máy tính / máy chủ của bạn).
POST/account/ai/uploads
curl -X POST https://moimedia.net/api/account/ai/uploads \
  -H "X-API-Key: $API_KEY" \
  -F "file=@./anh-mau.jpg"

# => { "url": "https://moimedia.net/uploads/ai/inputs/...", "name": "anh-mau.jpg", "mimeType": "image/jpeg", "size": 183204 }

Lịch sử tác vụ

GET/v1/generations?page=1&limit=20&status=succeeded&model={id}

Mới nhất trước, có phân trang: { "object": "list", "data": [...], "meta": { "total", "page", "limit", "totalPages" } }.

Số dư tài khoản

GET/account/credits
{
  "credits": 54000,           // số dư ví hiện có (VND)
  "concurrency": 3,           // số tác vụ được chạy cùng lúc
  "totalUsed": 126000,       // tổng tiền đã dùng (VND)
  ...
}

Lỗi & giới hạn

Lỗi trả mã HTTP 4xx/5xx kèm thông báo đọc được: { "statusCode": 400, "message": "...", "error": "Bad Request" }

MãÝ nghĩa
400Thiếu / sai tham số, tổ hợp không hợp lệ, số dư không đủ
401Key sai, hết hạn hoặc đã thu hồi
403Key không được gọi API này
404Model hoặc tác vụ không tồn tại / model đang tạm dừng
409Đang chạy quá số luồng của gói
429Gọi quá nhanh, chờ rồi thử lại

Giới hạn tốc độ: tạo tác vụ 20 lần/phút, báo giá và hỏi trạng thái 120 lần/phút, tải file 30 lần/phút.

Ví dụ hoàn chỉnh

Node.js (18+)

const BASE = "https://moimedia.net/api";
const headers = { "X-API-Key": process.env.API_KEY, "Content-Type": "application/json" };

async function call(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers });
  const body = await res.json();
  if (!res.ok) throw new Error(body.message);
  return body;
}

// 1) gửi input
let gen = await call("/v1/generations", {
  method: "POST",
  body: JSON.stringify({"model":"gemini-image","prompt":"Một chú mèo phi hành gia","size":"1:1","n":"1"}),
});

// 2) hỏi trạng thái tới khi xong
while (["queued", "processing"].includes(gen.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  gen = await call("/v1/generations/" + gen.id);
}
if (gen.status !== "succeeded") throw new Error(gen.error ?? gen.status);
console.log(gen.output.files.map((f) => f.url));

Python 3

import os, time, requests

BASE = "https://moimedia.net/api"
H = {"X-API-Key": os.environ["API_KEY"]}

def call(method, path, **kw):
    r = requests.request(method, BASE + path, headers=H, timeout=60, **kw)
    body = r.json()
    if not r.ok:
        raise RuntimeError(body.get("message"))
    return body

gen = call("POST", "/v1/generations", json={"model":"gemini-image","prompt":"Một chú mèo phi hành gia","size":"1:1","n":"1"})

while gen["status"] in ("queued", "processing"):
    time.sleep(5)
    gen = call("GET", f"/v1/generations/{gen['id']}")

if gen["status"] != "succeeded":
    raise RuntimeError(gen.get("error") or gen["status"])
print([f["url"] for f in gen["output"]["files"]])

Model hiện có

Bấm vào mã model để xem bảng Input (tham số, giá trị hỗ trợ) và Output của model đó.

modelTênoutputTham sốGiá
edit-multi-2k Sửa & Ghép Đa Ảnh AI 2Kimageimage_url, image2_url, image3_url, image4_url, prompt, aspect, n99 ₫ / ảnh
gemini-3-pro-image/edit-2 Gemini 3 Pro Image · chi tiết caoimageimage_urls, prompt, sizeTheo tham số
gemini-3-pro-image/image Gemini 3 Pro Image · chi tiết caoimageprompt, size, nTheo tham số
gemini-3.1-flash-image/edit-2 Gemini 3.1 Flash Image · nhanh, nétimageimage_urls, prompt, sizeTheo tham số
gemini-3.1-flash-image/image Gemini 3.1 Flash Image · nhanh, nétimageprompt, size, nTheo tham số
gemini-3.1-flash-lite-image Gemini 3.1 Flash Lite Image · siêu tốcimageprompt, size, nTheo tham số
gemini-3.1-flash-lite-image/edit Gemini 3.1 Flash Lite Image · siêu tốcimageimage_urls, prompt, sizeTheo tham số
gemini-image Gemini Image · 2K/4K, khuyên dùngimageprompt, size, nTheo tham số
gemini-image/edit Gemini Image · 2K/4K, khuyên dùngimageimage_urls, prompt, sizeTheo tham số
gemini-nano-banana-2.1 Gemini Nano Banana 2.1 · 2K/4Kimageprompt, size, nTheo tham số
gemini-nano-banana-2.1/edit Gemini Nano Banana 2.1 · 2K/4Kimageimage_urls, prompt, sizeTheo tham số
gpt-image-2-lowcost GPT Image 2.0 -Ảnh AI Studio 4Kimageprompt, aspect_ratio, resolution, image_url, image2_urlTheo tham số
gpt-image-2.5-flare/edit-3 GPT 2.5 Flare · chất lượng cao, nhanhimageimage_urls, prompt, sizeTheo tham số
gpt-image-2.5-flare/image-2 GPT Image 2.5 Flare - Chất lượng caoimageprompt, size, nTheo tham số
gpt-image-2.5-sunburst/edit-3 GPT 2.5 Sunburst · sửa ảnh chính xácimageimage_urls, prompt, sizeTheo tham số
gpt-image-2.5-sunburst/image-2 GPT Image 2.5 Sunburst · Chính xácimageprompt, size, nTheo tham số
gpt-image-2.6-flare GPT Image 2.6 Flare · tạo, sửa nhanhimageprompt, size, nTheo tham số
gpt-image-2.6-flare/edit GPT 2.6 Flare · tạo, sửa nhanhimageimage_urls, prompt, sizeTheo tham số
gpt-image-2.6-sunburst GPT Image 2.6 Sunburst · nhiều chi tiếtimageprompt, size, nTheo tham số
gpt-image-2.6-sunburst/edit GPT 2.6 Sunburst · nhiều chi tiếtimageimage_urls, prompt, sizeTheo tham số
gpt-image-2/edit-3 GPT 2imageimage_urls, prompt, sizeTheo tham số
gpt-image-2/image-3 GPT Image 2imageprompt, size, nTheo tham số
image-2k-eco Tạo Ảnh AI Siêu Nét - Banana 2Kimageprompt, aspect, n79 ₫ / ảnh
muse-image/edit-2 Museimageimage_urls, prompt, sizeTheo tham số
muse-image/image Muse Imageimageprompt, size, nTheo tham số
nano-2/image-outfit Nano 2imageimage_url, garment_url, outfit_part, background, prompt, aspect_ratio, resolutionTheo tham số
nano-banana2-lowcost Nano Banana 2 Low-Cost (Ảnh AI 4K)imageprompt, aspect_ratio, resolution, image_url, image2_urlTheo tham số
nano-image-to-image Ghép & Chỉnh sửa Ảnh AI Nano Bananaimageimage_url, image2_url, image3_url, image4_url, prompt, aspect, model_variant, n89 ₫ / ảnh
nano-pro/image-outfit Nano Proimageimage_url, garment_url, outfit_part, background, prompt, aspect_ratio, resolutionTheo tham số
nano-pro/image-upscale Nano Proimageimage_url, prompt, resolutionTheo tham số
nano-text-to-image Tạo Ảnh AI Nano Bananaimageprompt, aspect, model_variant, n89 ₫ / ảnh
seedream-5.0 Seedream 5.0imageprompt, reference_image_urls, aspect_ratioTheo tham số
seedream-5.0/image-outfit Seedream 5.0imageimage_url, garment_url, outfit_part, background, prompt, aspect_ratioTheo tham số
seedream-5.0/image-upscale Seedream 5.0imageimage_url, promptTheo tham số
virtual-tryon Thay Đồ Ảnh AI · Giữ Nguyên Mặt & Nềnimageimage_url, garment_url, outfit_part, background, aspect, n, prompt99 ₫ / ảnh
wf-upscale-ultra Ultra Fast Upscale 4Kimageimage_urlTheo tham số
google-omni-1.1-flash Google Omni 1.1 Flashvideoprompt, image_urls, quality, duration, aspect_ratio, nTheo tham số
grok-video-1.5 Grok Video 1.5videoprompt, image_urls, quality, duration, aspect_ratio, nTheo tham số
grok-video-3 Grok Video · Grok Imagine Video 1.5videoimage_url, prompt, duration, resolutionTheo tham số
grok-video/image-to-video Grok Video · Grok Imagine Video 1.5videoimage_url, prompt, duration, resolutionTheo tham số
image-to-video-1080p Ảnh thành Video 1080pvideoimage_url, image2_url, prompt, aspect, audio_mode888 ₫
image-to-video-15s-1080p Ảnh thành Video 1080p - 15svideoimage_url, image2_url, prompt, aspect, audio_mode1.250 ₫
image-to-video-15s-720p Ảnh thành Video 720p - 15svideoimage_url, image2_url, prompt, aspect, audio_mode999 ₫
image-to-video-720p Ảnh thành Video 720pvideoimage_url, image2_url, prompt, aspect, audio_mode777 ₫
kling-2.6 Kling 2.6 Provideoimage_url, prompt, duration, resolutionTheo tham số
kling-3.0 Kling 3.0 Mastervideoimage_url, prompt, duration, resolutionTheo tham số
kling-3.0-sieu-net Kling 3.0 Siêu Nétvideoimage_url, promptTheo tham số
kling-4.0 Kling 4.0videoimage_url, promptTheo tham số
kling-4.0/kling1k-i2v Kling 4.0 · 720p · 6svideoimage_url, promptTheo tham số
kling-4.0/kling1k-i2v-2 Kling 4.0 · 1080p · 4svideoimage_url, promptTheo tham số
minimax-h3-enhanced Minimax H3-RH Enhanced (Video 1080p • Tối đa 20s)videoprompt, duration, aspect_ratio, resolution, image_url, image2_url, video_url, audio_urlTheo tham số
motion-2.6 Motion 2.6 · 720p · Tối đa 13svideoimage_url, video_url, promptTheo tham số
motion-3.0 Motion 3.0 · 720p · Tối đa 7svideoimage_url, video_url, promptTheo tham số
motion-photo-bg-10s Motion Control Nền Ảnh 720p - Tối đa 10svideoimage_url, video_urlTheo tham số
motion-photo-bg-20s Motion Control Nền Ảnh 720p - Tối đa 20svideoimage_url, video_url, textTheo tham số
motion-v2 Motion control V2 - Trên 10svideoimage_url, video_url, quality, duration, orientation, keep_audioTheo tham số
text-to-video-1080p Văn bản thành Video 1080pvideoprompt, aspect, audio_mode249 ₫
text-to-video-15s-1080p Văn bản thành Video 1080p - 15svideoprompt, aspect, audio_mode1.250 ₫
text-to-video-15s-720p Văn bản thành Video 720p - 15svideoprompt, aspect, audio_mode999 ₫
text-to-video-720p Văn bản thành Video 720pvideoprompt, aspect, audio_mode199 ₫
vae-h3 VAE H3 · Ảnh thành video (Có tiếng)videoimage_url, prompt, duration, resolutionTheo tham số
vae-motion-control-1080p VAE Motion Control 1080p - Chất lượng caovideoimage_url, video_url, promptTheo tham số
vae-motion-control-7 VAE motion control 7videoduration, resolution, aspect_ratio, image_url, video_url, promptTheo tham số
vae-motion-control-8 VAE motion control 8 (Khuyên dùng - Tạo video nét)videoduration, resolution, aspect_ratio, image_url, video_url, promptTheo tham số
video-3 Chuyển văn bản hoặc ảnh thành videovideoprompt, image_urls, duration, sizeTheo tham số
video-enhance Làm nét video 4Kvideovideo_urlTheo tham số
eleven-speech ElevenLabs Speech (Lồng Tiếng & Giọng Đọc AI )audioprompt, voiceTheo tham số

API cũ (vẫn hoạt động)

Tích hợp trước đây theo mã công cụ vẫn chạy bình thường: POST /account/ai/tools/{key}/run với { "input": {...} }, POST /account/ai/tools/{key}/quote, GET /account/ai/tasks/{id}. Danh mục mã công cụ: GET /public/ai/tools. Tích hợp mới nên dùng API /v1 ở trên.