Hướng dẫn integrator (Tier A)
Tier A = sản phẩm gọi thẳng Gommo public API (v2.api.gommo.net + api.gommo.net). Không bắt buộc gateway, portal hay /gateway/* của repo này.
Operator / dealer
Tự host Gommo Developer (portal, /billing/*, BYOK, observability) là tuỳ chọn — xem Deploy và Portal & preview, không phải hợp đồng tích hợp mặc định.
Bắt đầu
| Bước | Doc |
|---|---|
| 1 | Nguyên tắc — hai host, Bearer, job async |
| 2 | Authentication — login, domain = domain đăng ký |
| 3 | Quickstart — một job ảnh end-to-end |
| 4 | Vòng đời request — create → poll → kết quả |
| 5 | Lỗi thường gặp · Webhooks — Tier A chỉ poll |
| 6 | Cookbook — recipe copy-paste (URL public) |
| 7 | SDK TypeScript — lộ trình 5 phút (createAndWait) |
| 8 | Đọc catalog · Models — không đoán ratio / mode |
Domain đăng ký (quan trọng)
Field domain là nơi user đăng ký trên Gommo (dealer). Không phải api.gommo.net hay v2.api.gommo.net.
| Ví dụ | Dùng |
|---|---|
| curl.exe | %REGISTRATION_DOMAIN% |
| PowerShell | $env:GOMMO_API_DOMAIN (throw nếu thiếu) |
| App | Giá trị theo user từ flow đăng ký |
Sai domain → auth/credit/billing lệch dealer. Xem Authentication.
Mode A vs self-host (B/C)
| Mode | Đối tượng | Base URL |
|---|---|---|
| A (Tier A) | Integrator production | https://v2.api.gommo.net, https://api.gommo.net |
| B/C | Operator chạy repo | {api-của-bạn}/gateway/* — Integration modes |
Doc Tier A (quickstart, models, cookbook) dùng Mode A. Mode B/C chỉ dưới Deploy → Self-host (nâng cao).
Preview chỉ có trên gateway
Tính năng chưa có trên public Gommo (BYOK, webhook observability, billing portal, usage aggregate gateway, OpenAI shim, …) có banner Sắp có trên nền tảng Gommo + roadmap. Không build Tier A phụ thuộc các API đó trừ khi chủ đích self-host.
Catalog EN (?lang=en)
Mô tả model EN: cache/catalog-descriptions.en.json. Warm offline:
npm run catalog:translate
npm run catalog:translate-th
npm run catalog:cache-smokeChecklist: doc/CATALOG-TEST.md trong repo.
Maintainer (repo)
Trước merge docs:
npm run docs:smoke
npm run portal:smoke # khi đổi copy portal; cần docs:stack + API :3001Sửa hàng loạt domain trong ví dụ: node scripts/normalize-domain-docs.mjs. Checklist nội bộ: doc/TRACK-C.md.