How to read the catalog

Every media job field (ratio, mode, resolution, duration, model id) must come from POST https://v2.api.gommo.net/ai/models?type=…. This page explains how to read that JSON before create + poll.

Step	Doc
List + pick fields	This page
Field reference	Parameters
HTTP create/poll	Media & jobs · Integration guide
Live browse	Models catalog

Never guess enums

Copying values from docs, another model, or a screenshot will fail upstream or produce wrong output. Always use your list response for that model id.

Request the 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%

type matches job types (image, video, music, tool types, …). Send the user’s registration domain — Authentication.

Response shape (typical)

Upstream wraps rows in data (array). Each row is one model:

{
  "success": true,
  "data": [
    {
      "model": "example_slug",
      "name": "Display name",
      "ratios": [{ "value": "1:1", "label": "Square" }],
      "modes": [{ "value": "low", "label": "Low" }],
      "resolutions": [{ "value": "2k", "label": "2K" }],
      "durations": ["5", "10"]
    }
  ]
}

Not every model exposes every array — omit fields that are missing for that model.

Pick the model id (URL path)

Create uses:

POST …/ai/jobs/{type}/{model_id}

The path segment may be labeled model, slug, model_id, or id_base in JSON. Use the value Gommo returns for that row (SDK: modelSlug() helper).

Read ratios, modes, resolutions, duration

Catalog field	Job form field	How to read
ratios[]	ratio	Often { value, label } — send value (sometimes a plain string in older rows)
modes[]	mode	Same pattern as ratios
resolutions[]	resolution	Same pattern
durations or durations[]	duration	Video/music — only listed seconds
—	prompt	Your app (not from catalog)

PowerShell example (first model, first ratio):

$m = $models.data[0]
$slug = $m.model ?? $m.slug
$ratio = $m.ratios[0]
if ($ratio -is [pscustomobject]) { $ratio = $ratio.value }

TypeScript (@ai-gateway/client): parseModelsList, modelSlug, pickFirstRatio — SDK five-minute path.

Tool and specialty models

Upscale, remove-bg, lipsync, etc. may use url, image, or other keys instead of prompt. Inspect the model row and Playground RESPONSE for that type.

English descriptions (?lang=en)

Docs site and GET /gateway/models?lang=en (operator/dev) can serve translated descriptions from cache (cache/catalog-descriptions.en.json). The allowed enums (ratio, mode, …) still come from the live POST /ai/models response — translations do not replace catalog validation.

Integrators: npm run catalog:cache-smoke in this repo; see doc/CATALOG-TEST.md.

After you have slug + fields

1. Create — form body: domain, prompt, catalog fields → Media reference
2. Poll — POST …/ai/jobs/{id_base}?media=… every 3.5s, max 80 → Request lifecycle
3. Errors — Common errors

Next

→ Parameters · Job types · Quickstart