Nguyên tắc

Nguyên tắc cốt lõi khi xây dựng trên Gommo — đọc Hướng dẫn integrator (Tier A), sau đó Quickstart hoặc Models.

Luồng request

App của bạn
  │
  ├─ v2.api.gommo.net  ──► models · create/poll jobs · upload image/video
  │
  └─ api.gommo.net     ──► login · /ai/me · chat · audio · job info

Tùy chọn: self-host Gommo Developer cho portal billing và BYOK preview — không bắt buộc khi tích hợp Gommo trực tiếp.

Hai upstream host

Host	Dùng cho
https://v2.api.gommo.net	Models, create/poll media jobs, upload
https://api.gommo.net	Login, profile/credits, chat, platform audio

Auth: Authorization: Bearer <access_token> qua HTTPS. Form platform và V2 gồm domain (cùng domain đăng ký tài khoản).

Nguyên tắc thiết kế

1. Gọi URL public Gommo

Integrator nhắm thẳng upstream host. Bản đồ đầy đủ → Gommo public API.

Thao tác	URL
List models	POST https://v2.api.gommo.net/ai/models?type={type}
Create job	POST https://v2.api.gommo.net/ai/jobs/{type}/{model_id}
Poll job	POST https://v2.api.gommo.net/ai/jobs/{id}?media={media}
Login	POST https://api.gommo.net/api/apps/go-mmo/auth/login
Me / credits	POST https://api.gommo.net/ai/me

2. Không đoán tham số model

ratio, mode, resolution, và duration bắt buộc lấy từ catalog model:

POST https://v2.api.gommo.net/ai/models?type=image
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

type=image&domain=%REGISTRATION_DOMAIN%

Đoán giá trị gây upstream từ chối hoặc chất lượng kém. Xem Models.

3. Job async, poll rõ ràng

Job media Gommo không push webhook về app mặc định. Client phải poll:

• 3500 ms interval
• 80 lần tối đa (~5 phút)
• POST …/ai/jobs/{id}?media=… đến trạng thái terminal

Poll phía client mỗi 3.5s, tối đa 80 lần — Gommo không webhook khi job hoàn thành.

4. Domain trong mọi form body

Gửi domain khớp domain đăng ký của user (dealer). Domain sai → lỗi auth, credit hoặc billing. Xem Authentication.

Portal multi-dealer có thể khóa domain theo dealer — xem Upstream hosts.

Docs portal multi-tenant có thể khóa domain theo dealer — xem Tenants.

5. User vs merchant credential

Credential	Vị trí	Dùng cho
User access_token	Client Bearer / form	Mọi user API call
GOMMO_ACCESS_TOKEN	Server env only	Merchant ops, catalog translate warm
ADMIN_API_KEY	Server env only	Self-hosted /vi/admin/*

Không expose merchant hoặc admin secret ra browser/mobile.

6. Billing trên platform auth host

Nạp credit dùng Gommo create_payment + payment_sync trên api.gommo.net. Site docs có thể wrap billing dưới /vi/billing/* khi self-host — xem Billing & credits.

7. Lỗi upstream

Gommo trả JSON với message, success, error. Kiểm tra HTTP status và body — không retry credential không đổi khi auth fail.

Ưu tiên

• Tốc độ integrator — Quickstart vài phút, Playground với URL public
• Trung thành catalog — không bịa enum; list models trước
• Host rõ ràng — v2 cho media, api cho auth/chat/audio

Khi nào nhắc /gateway/* trong docs

Mặc định: integrator gọi Gommo public hosts (Mode A). Không lead bằng /gateway/* trong Tier A (models, jobs, chat, upload, auth, cookbook).

Gateway thuộc docs khi: bảng so sánh Mode B/C, mục self-host tùy chọn, tính năng portal-only (BYOK, observability, usage, billing), deploy/MCP self-hosted. Runtime portal có thể proxy /gateway/* trên :5173 — đó là hạ tầng dev, không phải public contract.

Trang gateway-only: thêm tip Coming to Gommo platform sau H1 và link Roadmap nền tảng Gommo. Đây là preview những gì Gommo sẽ ship — không phải sản phẩm preview-only vĩnh viễn của Gommo Developer.

Tiếp theo

→ Roadmap nền tảng Gommo · Models · Quickstart · MCP & agents