FAQ

Common questions about integrating with Gommo and the optional Gommo Developer.

Upstream status

Catalog, jobs, and login call Gommo public API (v2.api.gommo.net, api.gommo.net). If upstream is down, /models/ and Playground Send will fail — docs and UI still load. Retry when upstream recovers.

Coming to Gommo platform

Features like BYOK, SDK, webhooks, and portal billing are previews of the Gommo platform — not permanent self-host-only APIs. See the Gommo platform roadmap.

Getting started

What is Gommo Developer vs calling Gommo directly?

Public Gommo API (recommended): call https://v2.api.gommo.net and https://api.gommo.net directly — see Gommo public API. No gateway required.

Gommo Developer (optional): self-host this repo for portal dev, billing, or BYOK previews — not required for standard Gommo API integration. See Deploy → Self-host (advanced).

What do I need to get started?

Direct integration (recommended):

• Gommo account (email + password + registration domain, e.g. <registration-domain>)
• HTTPS client — curl, PowerShell, or Playground
• Follow Quickstart

Where is the API playground?

/app/playground/ — sign in on the docs site. The Endpoints tab shows full public Gommo URLs per operation.

Authentication

How do I get a user token?

POST https://api.gommo.net/api/apps/go-mmo/auth/login with email, password, domain (registration domain). Response: access_token. See Authentication.

How do users change their login password?

POST https://api.gommo.net/api/apps/go-mmo/auth/change-password with access_token, domain, current_password, new_password (form). Not the same as AI project set_password. Self-host: POST {gateway}/gateway/auth/change-password (Bearer + JSON). See Account settings — change password.

How do users transfer credits to another username?

POST https://api.gommo.net/api/apps/go-mmo/users/sendBalances with user access_token, domain, type=credit_ai, username, value, message (form). Not merchant /admin/credits/send. Min 10,000 / max 20,000,000 per transfer; sender must keep > 500,000 credits after. Upstream may return HTTP 200 with error: 1 — parse message. Self-host: POST {gateway}/gateway/credits/transfer (Bearer + JSON). See Account — transfer credits.

Where is wallet transaction history (not usage-history)?

Dealer Account → Transaction History uses POST https://api.gommo.net/api/apps/go-mmo/users/paymentsHistory with user access_token, domain, limit (dealer UI often 500), time_start / time_end (0 = all time), optional currency_name, source, language (form). Response is usually { data: [...], runtime } — sum IN/OUT/NET client-side from fluctuation_type and value_change. Not POST /api/v2/usage-history (per-job stats/logs). Self-host: POST {gateway}/gateway/credits/transactions (Bearer + JSON). See Account — transaction history.

Where are manage-account session devices?

Dealer Account → Devices uses POST https://api.gommo.net/api/v2/devices with user access_token, domain, and action: register, list, rename, or disable. List/register usually send current_device_id and device_* from the browser; rename and disable target form device_id (session UUID from data.items[]), not id_base. Response is typically { success, message?, data } — list returns data.items and data.current_device_id. Self-host: POST {gateway}/gateway/devices (Bearer + JSON). See Account — session devices.

Where is the Support Center API?

Dealer Support uses POST https://api.gommo.net/api/apps/go-mmo/support/* — myTickets (list), create (subject, issue_type, description), detail and reply with public ticket_id_base (SUP-… — same as ticket_id_hash from create, not numeric ticket.id). Self-host: /gateway/support/tickets (+ /create, /detail, /reply) with Bearer + JSON. See Account — support tickets.

Where is the Partner Program API?

Dealer Partner Program (affiliate) uses POST https://api.gommo.net/api/apps/go-mmo/users/partner_program with action_type=status (ranks, rules, application) or apply (Join form: bank fields, accept_rules=1). Self-host: POST /gateway/partner-program with Bearer + JSON. Prefer application?.status over can_join alone for pending review. See Account — partner program.

Creator Rewards uses POST https://api.gommo.net/api/apps/go-mmo/users/creator_rewards with action_type=status, pool, or apply (Join with payout_pref=credit or cash + bank fields). Self-host: POST /gateway/creator-rewards. Prefer program.application?.status for pending review. See Account — creator rewards.

Do I send domain on every call?

Direct Gommo API (recommended): include domain in every form body matching the user's registration domain.

Operators who self-host may omit domain on some paths — see Deploy → Self-host (advanced).

What is the merchant token?

GOMMO_ACCESS_TOKEN in server .env — for /admin/* and legacy PayOS fulfillment only. Not required for default Gommo top-up or direct public API calls. Never in browser apps.

Models & jobs

Why did my job fail with invalid ratio/mode?

You guessed parameters. Always list models first and use values from the catalog. See Models.

How long does polling take?

Direct API: poll every 3.5s, max 80 attempts (~5 min).

Video jobs often need 1–5 minutes.

Does Gommo send webhooks when a job completes?

No on the public integrator API — poll job status client-side. Payment and gateway observability webhooks are different — see Webhooks (concepts).

Self-host (operators)

When do I need the self-hosted API?

Only if you deploy this repo for portal billing, BYOK, or dev proxy — not for normal Gommo integration. See Deploy → Self-host (advanced).

Billing

Do integrators need to integrate Gommo billing or guide users to top up Gommo credits?

No — for standard Gommo public API integration you only need users with a Gommo access_token and enough credits on their Gommo account (see Authentication).

• Your app's pricing (Stripe, your own payment rails, subscriptions, etc.) is your product — this site does not document how you charge your customers.
• Gommo credit topup (user pays for AI credits on their registration domain / dealer) is a separate concern. Tier A docs do not prescribe a production topup flow.
• Preview today: portal /app/credits/ and self-host /billing/* are Coming to Gommo platform — for operators testing checkout, not the default integrator contract. When Gommo ships official developer billing, use Gommo's domains and docs — not localhost:3001.

→ Gommo platform roadmap · Billing & credits (operators)

How do I top up credits?

Operators / portal preview (not required for Tier A integrators):

Default: Gommo top-up — requires self-hosted gateway: POST /billing/payment/create (user Bearer), then poll POST /billing/payment/sync until paid: true. Portal: /app/credits/. Recipe: Gommo topup.

Legacy (optional): PayOS via POST /billing/topup/create when PAYOS_* and merchant env are configured.

Why does billing fail or return an error?

Check GET /billing/status on your self-hosted gateway — expect billingMode: "gommo" and gommoPayment: true for the default flow.

Common issues:

• Bearer token does not match username in the request body
• Invalid packageId
• Legacy PayOS: payosConfigured or merchantReady is false

Why does /billing/topup/create return 503?

That path is legacy PayOS only. PayOS or merchant env is not configured. For new integrations use POST /billing/payment/create instead. Check GET /billing/status.

Is billing required to use Gommo APIs?

No — billing is optional topup. Users need Gommo credits (from upstream account or topup).

MCP & Cursor

Which MCP should I use in Cursor?

Recommended: Gommo remote MCP — 10 tools, token from /app/token/. JSON for Cursor, Claude, ChatGPT, and other hosts.

Production apps: HTTP to Gommo public API — see Gommo public API. Not MCP.

Optional: Gommo Developer MCP server only if IDE must call your own GATEWAY_URL. npm alias: @ai-gateway/mcp-server.

What can Gommo MCP do?

All 10 tools: account/credit, model catalog, image & video create, status & stream polling, task history, and notifications. See tool reference and use cases & prompts.

Can I use Gommo MCP outside Cursor?

Yes — any MCP client that supports remote url + custom headers. See Other MCP hosts. ChatGPT/Gemini web apps cannot use MCP; use HTTP to Gommo directly instead.

Is the token from /app/token/ the same as Gommo MCP?

Yes. Login returns a Gommo user access_token. Use it in Gommo MCP headers (Gommo-Token and Authorization: Bearer …) and as Authorization: Bearer … for HTTP calls to v2.api.gommo.net and api.gommo.net.

Do I need to run the gateway for MCP?

No for Gommo MCP — tools call Gommo's hosted MCP directly.

Yes only for the optional Gommo Developer MCP server (GATEWAY_URL required). npm alias: @ai-gateway/mcp-server.

What is the self-hosted MCP server?

The optional Gommo Developer MCP server lets merchants point Cursor tools at their gateway URL instead of Gommo remote MCP. See Self-hosted MCP. Published on npm as @ai-gateway/mcp-server. Most users should use Gommo MCP or direct HTTP.

Deploy & ops

When do I need CORS?

When a browser app on another origin calls a self-hosted gateway (e.g. localhost:5175 → localhost:3001). Not needed for direct Gommo API calls or server-side clients.

Set GATEWAY_CORS_ORIGIN comma-separated origins.

See Deploy & ops and Best practices.

Is /portal available in production?

Off by default (NODE_ENV=production). Enable with GATEWAY_PORTAL=true only if you accept the risk.

Still stuck?

→ Report feedback · Community