Principles

Core principles for building on Gommo — read Integrator guide (Tier A), then Quickstart or Models.

Request flow

Your app
  │
  ├─ v2.api.gommo.net  ──► models · create/poll jobs · upload image/video
  │
  └─ api.gommo.net     ──► login · /ai/me · chat · audio · job info

Optional: self-host Gommo Developer for portal billing and BYOK previews — not required for direct Gommo integration.

Two upstream hosts

Host	Use for
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> on HTTPS. Platform and V2 form bodies include domain (same as account registration domain).

Design principles

1. Call Gommo public URLs

Integrators target upstream hosts directly. Full map → Gommo public API.

Operation	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. Never guess model parameters

ratio, mode, resolution, and duration must come from the model catalog:

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%

Guessing values causes upstream rejection or silent quality issues. See Models.

3. Async jobs, explicit polling

Gommo media jobs do not push webhooks to your app by default. Your client must poll:

• 3500 ms interval
• 80 max attempts (~5 min)
• POST …/ai/jobs/{id}?media=… until terminal status

Poll client-side every 3.5s, max 80 attempts — Gommo does not webhook job completion.

4. Domain in every form body

Send domain matching the user's registration domain (dealer tenant). Wrong domain → auth, credit, or billing errors. See Authentication.

Multi-tenant docs portal may lock domain per dealer — see Upstream hosts.

5. User vs merchant credentials

Credential	Where	Used for
User access_token	Client Bearer / form	All user API calls
GOMMO_ACCESS_TOKEN	Server env only	Merchant ops, catalog translate warm
ADMIN_API_KEY	Server env only	Self-hosted /admin/*

Never expose merchant or admin secrets to browsers or mobile apps.

6. Billing on platform auth host

Credit topup uses Gommo create_payment + payment_sync on api.gommo.net. This docs site may wrap billing under /billing/* when self-hosted — see Billing & credits.

7. Upstream errors

Gommo returns JSON with message, success, error. Check HTTP status and body — do not retry unchanged credentials on auth failures.

What we optimize for

• Integrator speed — Quickstart in minutes, Playground with public URLs
• Catalog fidelity — never invent enums; list models first
• Clear hosts — v2 for media, api for auth/chat/audio

When to mention /gateway/* in docs

Default: integrators call Gommo public hosts (Mode A). Do not lead with /gateway/* in Tier A guides (models, jobs, chat, upload, auth, cookbook).

Gateway belongs in docs for: Mode B/C comparison tables, optional self-host sections, portal-only features (BYOK, observability, usage, billing), deploy/MCP self-hosted guides. Runtime portal code may proxy /gateway/* on :5173 — that is dev infrastructure, not the public contract.

Gateway-only pages: add a Coming to Gommo platform tip after the H1 and link Gommo platform roadmap. These features are previews of what Gommo will ship — not a permanent Gommo Developer preview-only product.

Next

→ Gommo platform roadmap · Models · Quickstart · MCP & agents