FAQ

Câu hỏi phổ biến về Gommo Developer và Gommo upstream.

Trạng thái upstream

Catalog, job và login gọi Gommo public API. Nếu v2.api.gommo.net hoặc api.gommo.net sập, /vi/models/ và Playground Send sẽ fail — docs và UI vẫn load. Thử lại khi upstream hồi.

Sắp có trên nền tảng Gommo

BYOK, SDK, webhook, billing portal… là xem trước nền tảng Gommo — không phải API self-host vĩnh viễn. Xem Roadmap nền tảng Gommo.

Bắt đầu

Gommo Developer khác gì gọi Gommo trực tiếp?

Gommo public API (khuyến nghị): gọi thẳng https://v2.api.gommo.net và https://api.gommo.net — xem Gommo public API.
Gommo Developer (tùy chọn): self-host cho portal/billing/BYOK — xem Deploy → Self-host nâng cao.

Cần gì để bắt đầu?

• Tài khoản Gommo (email + password + domain đăng ký, vd. <registration-domain>)
• Client HTTPS — curl, PowerShell, hoặc Playground
• Quickstart

API playground ở đâu?

/vi/app/playground/ — tab Endpoints hiện URL public Gommo.

Authentication

Lấy user token thế nào?

POST /api/apps/go-mmo/auth/login với email, password, domain (domain đăng ký). Response: access_token. Xem Authentication.

User đổi mật khẩu đăng nhập thế nào?

POST https://api.gommo.net/api/apps/go-mmo/auth/change-password — form access_token, domain, current_password, new_password. Khác set_password trên AI project. Self-host: POST {gateway}/gateway/auth/change-password (Bearer + JSON). Xem Cài đặt tài khoản — đổi mật khẩu.

User chuyển credit sang username khác thế nào?

POST https://api.gommo.net/api/apps/go-mmo/users/sendBalances — form user access_token, domain, type=credit_ai, username, value, message. Không phải merchant /admin/credits/send. Tối thiểu 10.000 / tối đa 20.000.000 mỗi lần; sau chuyển ví gửi phải còn > 500.000 credit. Upstream có thể HTTP 200 + error: 1 — đọc message. Self-host: POST {gateway}/gateway/credits/transfer (Bearer + JSON). Xem Chuyển credit.

Lịch sử giao dịch ví (không phải usage-history) ở đâu?

Dealer Transaction History dùng POST https://api.gommo.net/api/apps/go-mmo/users/paymentsHistory — form access_token, domain, limit (UI thường 500), time_start / time_end (0 = mọi thời gian), tùy chọn currency_name, source, language. Response thường { data, runtime } — tổng IN/OUT/NET tính phía client từ fluctuation_type và value_change. Không phải POST /api/v2/usage-history. Self-host: POST {gateway}/gateway/credits/transactions (Bearer + JSON). Xem Lịch sử giao dịch.

Thiết bị đăng nhập (Devices) ở đâu?

Dealer Account → Devices dùng POST https://api.gommo.net/api/v2/devices — form access_token, domain, action (register, list, rename, disable). List/register thường gửi current_device_id và device_*; rename / disable dùng device_id (UUID từ data.items[]), không phải id_base. Response thường { success, data: { items, current_device_id } } hoặc một row khi mutation. Self-host: POST {gateway}/gateway/devices (Bearer + JSON). Xem Thiết bị đăng nhập.

API Support Center ở đâu?

Dealer Support dùng POST https://api.gommo.net/api/apps/go-mmo/support/* — myTickets, create, detail, reply với ticket_id_base (SUP-…, trùng ticket_id_hash khi create). Self-host: /gateway/support/tickets (+ /create, /detail, /reply) Bearer + JSON. Xem Ticket hỗ trợ.

API Chương trình đối tác ở đâu?

Partner Program affiliate: POST https://api.gommo.net/api/apps/go-mmo/users/partner_program với action_type=status hoặc apply. Self-host: POST /gateway/partner-program Bearer + JSON. Xem Chương trình đối tác.

Creator Rewards: POST https://api.gommo.net/api/apps/go-mmo/users/creator_rewards với action_type=status, pool, hoặc apply (payout_pref=credit). Self-host: POST /gateway/creator-rewards. Xem Creator Rewards.

Có cần gửi domain mọi call?

Gommo public API (khuyến nghị): gửi domain trong form body trùng domain đăng ký user.

Operator self-host: xem Deploy → Self-host nâng cao.

Merchant token là gì?

GOMMO_ACCESS_TOKEN trong .env server — cho /vi/admin/* và fulfillment PayOS legacy. Không bắt buộc cho nạp credit Gommo mặc định. Không đưa vào browser.

Models & jobs

Job fail vì ratio/mode không hợp lệ?

Bạn đoán tham số. Luôn list models trước và dùng giá trị từ catalog. Xem Models.

Poll mất bao lâu?

Poll client mỗi 3.5s, tối đa 80 lần (~5 phút). Video thường 1–5 phút.

Gommo có webhook khi job xong không?

Không trên public integrator API — poll phía client. Webhook thanh toán / observability gateway là khác — Webhooks (khái niệm).

Self-host (operator)

Khi nào cần API self-host?

Chỉ khi deploy repo cho portal billing, BYOK, hoặc dev proxy — không cần cho tích hợp Gommo thông thường. Xem Deploy → Self-host nâng cao.

Billing

Integrator có cần tích hợp billing Gommo hoặc hướng dẫn user nạp credit Gommo?

Không — tích hợp Gommo public API chuẩn chỉ cần user có access_token Gommo và đủ credit trên tài khoản Gommo (xem Authentication).

• Giá / thanh toán app của bạn (Stripe, cổng thanh toán riêng, subscription, …) là sản phẩm của bạn — site này không hướng dẫn cách thu tiền khách hàng của bạn.
• Nạp credit Gommo (user trả để có credit AI trên domain đăng ký / dealer) là chuyện khác. Docs Tier A không quy định luồng production nạp credit.
• Preview hiện tại: portal /vi/app/credits/ và self-host /vi/billing/* là Coming to Gommo platform — cho operator test checkout, không phải contract mặc định cho integrator. Khi Gommo ship billing developer chính thức, dùng domain và docs của Gommo — không phải localhost:3001.

→ Roadmap Gommo platform · Billing & credits (operator)

Nạp credit thế nào?

Operator / preview portal (không bắt buộc cho integrator Tier A):

Mặc định: nạp credit Gommo — POST /billing/payment/create (Bearer user), rồi poll POST /billing/payment/sync đến khi paid: true. Portal: /vi/app/credits/. Recipe: Gommo topup.

Legacy (tùy chọn): PayOS qua POST /billing/topup/create khi đã cấu hình PAYOS_* và merchant. Xem PayOS nạp credit (legacy).

Billing lỗi hoặc trả lỗi — kiểm tra gì?

Gọi GET /billing/status — flow mặc định cần billingMode: "gommo" và gommoPayment: true.

Lỗi thường gặp:

• Bearer không khớp username trong body
• packageId không hợp lệ
• PayOS legacy: payosConfigured hoặc merchantReady là false

/billing/topup/create trả 503?

Path này chỉ dành cho PayOS legacy. PayOS hoặc merchant env chưa cấu hình. Tích hợp mới nên dùng POST /billing/payment/create. Kiểm tra GET /billing/status.

Billing có bắt buộc để dùng Gommo API?

Không — billing là nạp tùy chọn. User cần credit Gommo (tài khoản upstream hoặc topup).

MCP & Cursor

Nên dùng MCP nào trong Cursor?

Khuyên dùng: Gommo remote MCP — 10 tools, token /vi/app/token/. JSON cho Cursor, Claude, ChatGPT và host khác.

App production: HTTP tới Gommo public API — xem Gommo public API. Không phải MCP.

Tùy chọn: Gommo Developer MCP server khi IDE phải gọi GATEWAY_URL riêng. npm alias: @ai-gateway/mcp-server.

Gommo MCP làm được gì?

10 tools: tài khoản/credit, catalog, tạo ảnh/video, poll status/stream, lịch sử job, thông báo. Xem tools và use cases.

Dùng Gommo MCP ngoài Cursor được không?

Có — client MCP hỗ trợ remote url + headers. Host khác. ChatGPT/Gemini web không dùng MCP — dùng HTTP.

Token /app/token/ có dùng được Gommo MCP không?

Có. Đăng nhập/đăng ký trả access_token user Gommo. Dùng trong header Gommo MCP (Gommo-Token + Authorization: Bearer …) và Authorization: Bearer … cho HTTP tới v2.api.gommo.net và api.gommo.net.

Có cần chạy gateway để dùng MCP?

Không với Gommo MCP — tool gọi MCP host sẵn của Gommo.

Có chỉ với Gommo Developer MCP server (GATEWAY_URL). npm alias: @ai-gateway/mcp-server.

Self-hosted MCP server là gì?

Gommo Developer MCP server — package tùy chọn cho merchant muốn tool Cursor gọi gateway URL riêng thay vì Gommo remote MCP. Xem Self-hosted. Trên npm: @ai-gateway/mcp-server. Đa số user dùng Gommo MCP.

Deploy & ops

Khi nào cần CORS?

Khi browser app origin khác gọi API (vd. localhost:5175). Không cần cho /vi/portal hoặc client server-side.

Set GATEWAY_CORS_ORIGIN nhiều origin, phân cách dấu phẩy.

Xem Deploy (VI) và Best practices (VI).

/portal có trên production không?

Mặc định tắt (NODE_ENV=production). Bật GATEWAY_PORTAL=true nếu chấp nhận rủi ro.

Vẫn kẹt?

→ Góp ý · Community