LogoAPI

Public API · v1

Tài liệu API

Một API key duy nhất cho ảnh, video, giọng đọc (TTS), LLM chat và nâng cấp ảnh/video. REST thuần, trả job id, poll tới khi xong.

docs.md cho AI agent
Base URLhttps://api.tramsangtao.com/v1
HeaderAuthorization: Bearer sk_live_...
Rate limit100 request / phút

Bắt đầu nhanh

Tạo key → POST /v1/generate → poll job. /v1/generate nhận JSON; các endpoint cũ (Legacy) nhận JSON hoặc form-data.

1. API key của bạn

Key dạng sk_live_.... Quản lý chi tiết tại /developers/keys. Catalog model text + giá token của LLM API ở Chợ model.

Đăng nhập để tạo và quản lý API key.

2. Request đầu tiên

Tạo ảnh — POST /v1/generate — bash
curl -X POST https://api.tramsangtao.com/v1/generate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A futuristic city",
    "params": {
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'
Lấy kết quả — bash
curl https://api.tramsangtao.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_live_xxx"

Video, ảnh tham chiếu, báo giá dry_run, Idempotency-Key, webhook_url: xem POST /v1/generate.

Một body cho mọi model

POST /v1/generate tạo ảnh, video và Motion Control; GET /v1/models/{id} cho biết model nhận gì, dry_run báo giá trước.

Job bất đồng bộ

Ảnh/video/upscale trả job_id ngay, poll /v1/jobs/{id} để lấy link (outputs[]).

Trả ngay

TTS Edge/CapCut và LLM chat trả kết quả trong chính response.

Trừ credit

Tính theo bảng giá model; job fail được hoàn credit tự động.

Xác thực & Base URL

Mọi request dùng Bearer token. Không nhúng key vào code phía client (web, app).

Header
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Giữ key an toàn

Key gọi được toàn bộ API và trừ credit thật. Nếu nghi ngờ lộ, thu hồi key trong /developers/keys rồi tạo key mới.
Base URL (v1)
https://api.tramsangtao.com/v1

Loại key

shared trừ credit của tài khoản · budgeted có hạn mức riêng · standalone dùng pool credit do admin nạp. Response trả kèm pool và balance_remaining.

Dùng với AI Agent

Đưa link markdown cho Claude / ChatGPT / Cursor — agent fetch toàn bộ docs (model, endpoint, ví dụ curl) trong 1 request.

/docs.md

Prompt mẫu: “Đọc /docs.md và viết script tạo ảnh”

Kết nối qua MCP Server

Cho Claude / ChatGPT / VS Code / Cursor tự tạo ảnh, video bằng tài khoản của bạn — không cần viết code.

Bước 1

Dùng với agent của bạn

Bấm agent bạn đang dùng — trang cài đặt mở sẵn, đăng nhập tài khoản là xong, không cần API key.

Hoặc cấu hình tay bằng API key

https://mcp.tramsangtao.com/mcp
Terminal — flags đứng TRƯỚC tên server — bash
claude mcp add --transport http --header "Authorization: Bearer sk_live_..." tramsangtao https://mcp.tramsangtao.com/mcp
Xem 32 tools có sẵn

Tạo ảnh / video / Motion Control: get_model → generate → wait_for_job. Ba tool generate_image / generate_video / generate_motion là đời cũ, vẫn chạy.

get_model— Model nhận tham số + media gì, giá live (gọi trước generate)
generate— Tạo ảnh / video / Motion Control qua POST /v1/generate; dry_run=true để báo giá
generate_image— Tạo ảnh (T2I / I2I) — tool cũ, dùng khi generate trả family_not_enabled
generate_video— Tạo video (T2V / I2V, tự route Seedance) — tool cũ
generate_motion— Motion Control từ video tham chiếu — tool cũ (mới: generate với motion-control-*)
generate_kol_video— Avatar nói theo audio (KOL AI)
wait_for_job— Chờ job xong, trả URL kết quả
get_job— Xem trạng thái 1 job
get_balance— Xem số credit còn lại
get_limits— Xem giới hạn chạy song song / hàng đợi
list_models— Danh sách model + giá (live)
upload_from_url— Nhập ảnh/video/audio ngoài vào CDN (generate tự nhập link công khai)
upload_media_to_cdn— Như upload_from_url, tên rõ nghĩa hơn cho MCP client
extract_media— Tách media từ link TikTok/YouTube (miễn phí)
generate_tts— Đọc chữ thành giọng (Edge / CapCut / Resona)
list_tts_engines— Danh sách engine TTS + giá (miễn phí)
list_tts_voices— Danh sách giọng đọc theo engine
wait_for_tts_job— Chờ job TTS xong, trả audio_url
get_tts_job— Xem trạng thái 1 job TTS
llm_chat— Chat LLM (Gemini/GPT), tính theo token
list_llm_models— Danh sách model LLM + giá token
list_workflow_nodes— Workflow: loại node, cổng, field dùng trong spec (miễn phí)
create_workflow— Workflow: dựng từ spec gọn, KHÔNG chạy — trả review_url cho user xem
update_workflow— Workflow: thay toàn bộ graph (409 nếu user vừa sửa tay)
get_workflow— Workflow: đọc lại spec + phần user sửa tay
delete_workflow— Workflow: xoá workflow do key này tạo
list_workflows— Workflow: danh sách của key này
get_review_link— Workflow: review_url mới (dùng một lần)
run_workflow— Workflow: chạy (tốn credit, không tự retry)
get_workflow_run— Workflow: snapshot run + từng node
wait_for_workflow_run— Workflow: chờ run kết thúc
stop_workflow_run— Workflow: dừng run đang chạy

Ảnh, Video & Motion

Một endpoint cho mọi model ảnh, video và Motion Control: POST /v1/generate. Trả job_id ngay, lấy kết quả bằng GET /v1/jobs/{job_id}.

Tạo ảnh / video / Motion Control — một body cho mọi model

Gửi model + prompt (kèm params, media nếu model cần) → nhận job_id ngay. Lấy kết quả bằng GET /v1/jobs/{job_id}.

Body JSON

modelstring · bắt buộc
Id model, ví dụ nano-banana-pro — chọn ở khung bên dưới.
promptstring
Mô tả nội dung. Đa số model bắt buộc.
server_idstring
Server chạy job (vip1, fast…). Bỏ trống = server mặc định.
paramsobject
Object tuỳ chọn của model, ví dụ {"aspect_ratio": "16:9", "duration": 5}. Tên và giá trị hợp lệ của từng model: khung bên dưới. Bỏ trống = mặc định.
medialist
Mảng file đầu vào, mỗi file một phần tử {"role": "…", "url": "https://…"}. role = ô media của model — khung bên dưới ghi tên.
  • File đã upload: gửi file_id thay cho url.

Model này cần gửi gì?

Chọn model và server — bảng dưới và request mẫu bên cạnh đổi theo.

model: "nano-banana-pro"·server_id:

prompt

promptbắt buộc
Mô tả nội dung, gửi ở "prompt": "…"

params

Gửi trong "params": { "tên": giá trị }. Bấm một giá trị để thử — request mẫu bên cạnh đổi theo. Bỏ trống = mặc định (viền đứt khi đã chọn ô khác).

resolutionChất lượng · đổi giá
aspect_ratioTỉ lệ
speedTốc độ · đổi giá

media

Mỗi file một phần tử trong "media": [ { "role", "url" } ], role lấy đúng tên bên dưới; file đã upload thì gửi file_id thay cho url.

reference_imagetuỳ chọn, ≤ 5
Ảnh tham chiếu · image{"role": "reference_image", "url": "https://…"}

Giá và cấu hình đang áp dụng (live): GET /v1/models/nano-banana-pro.

Request — Nano Banana PRO — bash
curl -X POST https://api.tramsangtao.com/v1/generate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "server_id": "vip1",
    "prompt": "Một thành phố tương lai lúc hoàng hôn",
    "params": {
      "resolution": "1k",
      "aspect_ratio": "9:16",
      "speed": "fast"
    }
  }'
200 OK — json
{
  "job_id": "3f0c9d7e-…",
  "status": "processing",
  "model": "nano-banana-pro",
  "server_id": "vip1",
  "mode": "references",
  "params": {
    "resolution": "1k",
    "aspect_ratio": "9:16",
    "speed": "fast",
    "count": 1
  },
  "changed": [],
  "ignored": [],
  "warnings": [],
  "cost_key": "1k-fast",
  "credits_cost": 100,
  "credits_remaining": 900,
  "poll_url": "/v1/jobs/3f0c9d7e-…"
}

Số credit là minh hoạ — giá thật: thêm dry_run hoặc xem Chợ model. cost_key = hàng giá đã áp, trùng khoá trong prices của GET /v1/models/{id}. status = pending khi job chờ slot trống của key.

TTS — Giọng đọc

3 engine: Edge (miễn phí), CapCut (miễn phí, ≤300 ký tự) và Resona (premium, đa giọng hội thoại). Tính tiền theo mỗi 100 ký tự.

Edge / CapCut trả audio ngay

Hai engine này tạo audio đồng bộ nên response của /tts/generate đã có audio_url (status=completed). Resona chạy job thật → poll GET /v1/tts/jobs/{job_id}. Không đủ slot đồng thời thì API trả 429 thay vì xếp hàng.

LLM Chat — thuần text

API tương thích OpenAI: đổi base_url + api_key là dùng được OpenAI SDK. Tính tiền theo token (input + output).

Cách tính tiền

max(min_charge, ceil(input/1M × giá_in + output/1M × giá_out)). Nếu ví không đủ cho input + min charge, API trả 402 TRƯỚC khi gọi model. Response có thêm x_credits_charged, x_remaining_balance, x_conversation_id.

Upscale — Nâng cấp ảnh & video

Tăng độ nét bằng Topaz. Không đổi nội dung, không cần prompt. Ảnh tính theo mỗi ảnh; video tính theo giây của video gốc.

KOL AI

Tạo avatar nói theo ảnh + audio. Motion Control đã chuyển sang POST /v1/generate (mục Ảnh, Video & Motion); route cũ POST /v1/motion/generate nằm ở mục Legacy.

Upload file

Có link công khai thì không cần upload: gửi thẳng vào media[].url của POST /v1/generate. Upload khi file nằm trên máy bạn, hoặc link quá lớn / quá chậm để server tải kịp lúc tạo job.

Dùng file đã upload

  • Trong POST /v1/generate: "media": [{"role": "start_frame", "file_id": "inp_…"}]. Route cũ (Legacy) dùng url trả về.
  • Giới hạn: ảnh 30MB · video 100MB · audio 50MB, với mọi cách upload.
  • file_id chỉ dùng được với key cùng tài khoản; upload chưa xong → 400 file_not_ready.
  • File được giữ có thời hạn (expires_at trong trạng thái upload). Gửi kèm header Idempotency-Key để gọi lại không tạo bản thứ hai.

Gửi link thẳng vào media[].url

  • Link http(s) công khai, cổng mặc định, không user:pass@; link trỏ về địa chỉ nội bộ bị từ chối (kể cả qua redirect, tối đa 3 lần).
  • Nhận theo nội dung file: ảnh JPEG / PNG / WebP, video MP4 / MOV / WebM, audio MP3 / WAV / M4A. Trang web, SVG… → source_not_media.
  • Tối đa 30MB ảnh · 100MB video · 50MB audio; ≤ 16 link mỗi lần gọi. Server tải trong lúc tạo job (tối đa khoảng 50 giây) — link lớn hoặc chậm thì upload trước.

File trên máy

· gửi file trực tiếp

File lớn, mạng yếu

· presign → PUT → confirm

Link lớn hoặc chậm

· server tải nền

Job & Tiện ích

Poll trạng thái job ảnh/video/motion/upscale, và trích link tải từ mạng xã hội.

Tài khoản & Models

Số dư, giới hạn đồng thời, danh sách model và bảng giá chi tiết theo server.

Tính tiền khi gọi API

Job tạo bằng API tính theo giá gốc (không áp giảm giá trên web), trừ vào ví mà key đang dùng: ví tài khoản (key dùng chung) hoặc hạn mức riêng của key. Gói Unlimited chỉ áp cho API khi gói có quyền API. Job lỗi được hoàn credit tự động.

Dashboard

Thông tin key, lịch sử job và thống kê sử dụng — dùng để dựng dashboard riêng cho khách của bạn.

Legacy — route tạo ảnh / video / motion cũ

POST /v1/image/generate, /v1/video/generate, /v1/seedance/generate, /v1/motion/generate vẫn chạy với body giữ nguyên, chưa có ngày ngừng (nếu có sẽ báo bằng header Sunset). Response kèm Deprecation: true và Link tới /v1/generate. Model mới chỉ có trên /v1/generate. KOL AI, Upscale và TTS vẫn dùng endpoint riêng — không phải legacy.

Đổi từ route cũ sang POST /v1/generate

POST /v1/image/generate · /v1/video/generate · /v1/seedance/generate · /v1/motion/generate
một route: POST /v1/generate (model quyết định)
aspect_ratio · resolution · speed · quality · audio
cùng tên, đặt trong params
duration: "5s" hoặc 5
params.duration: 5 (số nguyên giây)
hdr_format (Seedance 2.5)
params.hdr_format
route ảnh: img_url / image_urls
media: [{role: "reference_image", url}, …]
route video: img_url, hoặc image_urls [đầu, cuối] ở chế độ frames
media: [{role: "start_frame", url}, {role: "end_frame", url}]
route video: image_urls ở chế độ references (H3 / Wan / Veo ingredients)
media: [{role: "reference_image", url}, …]
Seedance img_urls / img_url
media: [{role: "reference_image", url}, …]
veo_mode (frames / ingredients) · image_mode (frames / references)
mode (hoặc để server suy từ role)
video_url(s) — video tham chiếu
media: [{role: "reference_video", url}]
Seedance audio_url(s) — audio tham chiếu
media: [{role: "reference_audio", url}]
motion: motion_video_url (+ video_cover_url)
media: [{role: "motion_video", url}] (3–30 giây, không cần cover)
motion: character_image_url / file character_image
media: [{role: "character_image", url}] (file: upload trước, gửi file_id)
motion: mode (std / pro) hoặc resolution
params.resolution (720p = std, 1080p = pro). Mặc định khác nhau: route cũ 720p, /v1/generate 1080p
motion: duration
không có — video ra dài bằng video nguồn, tính tiền theo giây của nó (server đo)
motion: /motion/upload-image · /motion/upload · /motion/estimate-cost
không cần: link hoặc file_id trong media[], dry_run để biết giá (các route phụ vẫn chạy cho route cũ)
response job_id · poll GET /v1/jobs/{id}
giữ nguyên
GET /v1/models/specs
GET /v1/models/{id} — một model, tên công khai, giá, endpoints

Mã lỗi

Lỗi trả về khi gọi request (HTTP 4xx / 5xx) không trừ credit. Lỗi xảy ra sau khi job đã tạo nằm trong trạng thái job.

Endpoint mới (/v1/generate, TTS, Upscale) — json
{
  "detail": {
    "error": {
      "code": "unknown_role",
      "message": "role 'logo' không có ở model này.",
      "param": "media[0]",
      "allowed": ["start_frame", "end_frame"],
      "details": {}
    }
  }
}
Route cũ (Legacy) và các endpoint khác — json
{
  "detail": "prompt is required"
}

Đọc lỗi thế nào

  • Endpoint mới: xử lý theo error.code; param chỉ trường cần sửa, allowed liệt kê giá trị hợp lệ (nếu có).
  • Route cũ: detail là chuỗi hoặc object tuỳ endpoint — dựa vào HTTP status.
  • Job lỗi sau khi tạo: GET /v1/jobs/{id} (và webhook) trả status: "failed", error (mô tả cho người đọc) và error_code; credit được hoàn tự động. error_code: content_policy (nội dung bị kiểm duyệt — đổi prompt / ảnh), invalid_input (đầu vào không dùng được — đổi file / tham số), timeout (quá thời gian — gửi lại), generation_failed (lỗi phía nhà cung cấp hoặc của chúng tôi — gửi lại sau).
400Bad Request
Thiếu tham số hoặc sai định dạng. Ở /v1/generate, error.param chỉ trường cần sửa, error.allowed liệt kê giá trị hợp lệ; invalid_value: giá trị model / server không có khi gửi strict: true. Route cũ: còn lỗi gọi sai endpoint (vd model seedance ở /video/generate).
401Unauthorized
API key sai hoặc thiếu header Authorization.
402Insufficient Funds
Không đủ credit. Nạp thêm hoặc dùng key có pool riêng.
403Forbidden
Key không có quyền, hoặc model đang bị tắt.
404Not Found
Job ID / tài nguyên không tồn tại (hoặc không thuộc key này).
409Conflict
idempotency_in_progress: request cùng Idempotency-Key còn đang chạy. family_not_enabled: model chưa mở trên /v1/generate — gọi model đó bằng route trong details.legacy_endpoint (body theo mục Legacy); GET /v1/models/{id} → endpoints.generate = null cho biết trước.
413Payload Too Large
source_too_large: file ở link media vượt giới hạn dung lượng (30MB ảnh · 100MB video · 50MB audio).
422Unprocessable
idempotency_key_reused: Idempotency-Key đã dùng cho request có body khác.
429Too Many Requests
Vượt rate limit (100 req/phút) hoặc hết slot đồng thời — chờ rồi thử lại.
500Internal Server Error
Lỗi phía chúng tôi — báo support kèm job_id.
502Provider Error
Provider từ chối/lỗi (TTS, LLM). Credit đã trừ được hoàn tự động.
503Service Unavailable
Provider quá tải hoặc engine chưa cấu hình.