Thực hành tốt

Pattern khuyến nghị cho tích hợp Gommo public API ổn định.

1. Luôn list models trước job

Không hard-code hoặc đoán ratio, mode, resolution, hoặc duration.

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%

Dùng giá trị từ mảng response của model đó. Giá trị sai gây upstream từ chối hoặc output kém.

→ Models · Media jobs

2. Poll rõ ràng

Chiến lược	Khi dùng
Client poll POST …/ai/jobs/{id}?media=…	Mọi tích hợp direct — 3500 ms × 80 max
UI có progress	Cùng poll loop; hiện status từ response
Self-host wait: true	Chỉ operator — Deploy nâng cao

Gommo không webhook khi job hoàn thành mặc định. Lên kế hoạch timeout và đường retry cho user.

3. Ưu tiên public API trực tiếp

Gọi v2.api.gommo.net và api.gommo.net từ backend hoặc client tin cậy. Self-host Gommo Developer chỉ khi cần portal billing, BYOK, hoặc dev proxy.

4. Giữ secret trên server

Nên	Không
Login từ backend hoặc token user ngắn hạn	Ship GOMMO_ACCESS_TOKEN ra browser
Merchant key chỉ trong deploy secrets	Commit .env
User Bearer cho generation	Expose admin key trên frontend

→ Privacy & security

5. CORS khi browser gọi Gommo cross-origin

Browser gọi thẳng v2.api.gommo.net cần CORS policy Gommo. Pattern thường: backend của bạn proxy token user sang Gommo.

Playground same-origin dùng site proxy cho tiện dev.

6. Chat: luôn gửi messages

Upstream yêu cầu messages không rỗng cho chat:

POST https://api.gommo.net/api/v2/chat
Content-Type: application/x-www-form-urlencoded

access_token=…&domain=%REGISTRATION_DOMAIN%&action=chat&query=Hello&messages=[…]

Streaming: dùng action=stream và consume SSE.

→ Chat

7. Upload trước job khi cần

Flow image-to-video và edit:

1. POST https://v2.api.gommo.net/ai/upload/image (hoặc video) → lấy URL
2. Truyền URL trong job form (tên field từ catalog model)
3. Create job và poll

8. Xử lý lỗi upstream

Kiểm tra success, message, và HTTP status. Không retry credential không đổi khi auth fail.

Triệu chứng	Hành động thường
Token / domain errors	Login lại; xác minh domain đăng ký
Validation	Sửa form field từ catalog
Insufficient credits	Top up qua platform payment
Rate limit	Back off

9. Tách billing khỏi generation

Nạp credit dùng endpoint payment api.gommo.net. Site docs có thể expose /vi/billing/* khi self-host — xem Billing & credits.

10. Test playground trước

/vi/app/playground/ — tab Endpoints hiện URL public đầy đủ theo thao tác.

Sau đó tích hợp từ app với cùng token flow như Quickstart.

Tiếp theo

→ Principles · Privacy · FAQ