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.
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
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"
}
}'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).
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxGiữ key an toàn
https://api.tramsangtao.com/v1Loại key
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.
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/mcpclaude mcp add --transport http --header "Authorization: Bearer sk_live_..." tramsangtao https://mcp.tramsangtao.com/mcpXem 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_enabledgenerate_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 jobget_balance— Xem số credit còn lạiget_limits— Xem giới hạn chạy song song / hàng đợilist_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 clientextract_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 enginewait_for_tts_job— Chờ job TTS xong, trả audio_urlget_tts_job— Xem trạng thái 1 job TTSllm_chat— Chat LLM (Gemini/GPT), tính theo tokenlist_llm_models— Danh sách model LLM + giá tokenlist_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 xemupdate_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 taydelete_workflow— Workflow: xoá workflow do key này tạolist_workflows— Workflow: danh sách của key nàyget_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 nodewait_for_workflow_run— Workflow: chờ run kết thúcstop_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_idthay chourl.
- File đã upload: gửi
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"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{"role": "reference_image", "url": "https://…"}Giá và cấu hình đang áp dụng (live): GET /v1/models/nano-banana-pro.
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"
}
}'{
"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
/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.
File trên máy
Gửi file trong một request (multipart). Nhanh, đơn giản nhất.
POST /files/upload/image · video · audio
→ file_id ngay (audio: poll tới ready)
File lớn, mạng yếu
Ảnh / video đi thẳng lên kho, không qua server API — không lo timeout.
presign → PUT → confirm
→ file_id sau bước confirm
Link lớn hoặc chậm
Server tải nền, không bị giới hạn thời gian tải như lúc tạo job.
upload-url → poll status
→ file_id khi status = ready
Dùng file đã upload
- Trong
POST /v1/generate:"media": [{"role": "start_frame", "file_id": "inp_…"}]. Route cũ (Legacy) dùngurltrả về. - Giới hạn: ảnh 30MB · video 100MB · audio 50MB, với mọi cách upload.
file_idchỉ 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_attrong trạng thái upload). Gửi kèm headerIdempotency-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ếpFile lớn, mạng yếu
· presign → PUT → confirmLink lớn hoặc chậm
· server tải nềnJob & 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
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(modelquyế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ửifile_id)- motion: mode (std / pro) hoặc resolution
params.resolution(720p = std, 1080p = pro). Mặc định khác nhau: route cũ 720p,/v1/generate1080p- 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_idtrongmedia[],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.
{
"detail": {
"error": {
"code": "unknown_role",
"message": "role 'logo' không có ở model này.",
"param": "media[0]",
"allowed": ["start_frame", "end_frame"],
"details": {}
}
}
}{
"detail": "prompt is required"
}Đọc lỗi thế nào
- Endpoint mới: xử lý theo
error.code;paramchỉ trường cần sửa,allowedliệt kê giá trị hợp lệ (nếu có). - Route cũ:
detaillà 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.
