Request lifecycle (media jobs)

Image, video, music, and tool jobs on https://v2.api.gommo.net are asynchronous. A successful create returns a job id immediately; your app polls until a result URL appears or you give up.

This is the same flow as Quickstart step 3 — explained in one place.

Tier A default

Poll on the public API. Job webhooks in this repo’s Observability UI are self-host gateway preview only — not the Gommo public integrator contract. See Gommo platform roadmap.

Flow

sequenceDiagram
  participant App
  participant V2 as v2.api.gommo.net
  App->>V2: POST /ai/jobs/{type}/{model}
  V2-->>App: job id (id_base)
  loop Every 3.5s, max 80
    App->>V2: POST /ai/jobs/{id}?media=...
    V2-->>App: pending or result_url
  end

Step	What you do
1	POST /ai/models?type=… — read slug, ratio, mode, etc. from catalog (How to read the catalog)
2	POST /ai/jobs/{type}/{model_id} — form body includes domain, prompt, catalog fields
3	Save id_base (job id) from create response
4	POST /ai/jobs/{id_base}?media={image|video|music} — repeat until terminal
5	Download or store result_url / file_url from poll JSON

Poll media must match job type (image, video, or music). Wrong media → confusing poll bodies.

Timing (documented defaults)

Parameter	Value
Interval	3500 ms between poll requests
Max attempts	80 (~4.7 minutes wall time)
Auth on poll	Bearer and/or access_token + domain in form body (same registration domain as create)

Gateway self-host can use wait: true on POST /gateway/jobs/* — that is Mode B, not required for Tier A. See Deploy → Self-host (advanced).

When is the job “done”?

Treat the job as successful when the poll response includes a result URL, for example:

• imageInfo.result_url / resultUrl (image)
• videoInfo / music equivalents — shape varies by type

Also check upstream success flags and status strings in the JSON. Do not assume a single global enum — log one full poll response during integration and map fields for your models.

Treat as failed when:

• Poll JSON indicates failure, moderation, or error (e.g. success: false, or status text containing fail/error/cancel — inspect upstream message)
• You exhaust 80 attempts without a result URL → timeout on your side

Full field map: Media & jobs reference.

Create response: get the job id

Create responses nest id_base under imageInfo, data, or top level depending on type. Example (PowerShell):

$jobId = $created.imageInfo.id_base ?? $created.data.id_base ?? $created.id_base
if (-not $jobId) { throw 'No job id in create response — log JSON and fix payload' }

Minimal poll loop

See Cookbook: Async job + poll for copy-paste PowerShell. TypeScript: createAndWait on @ai-gateway/client runs the same poll defaults. First image job (wait) uses blocking wait in Playground; production apps use a loop or the SDK.

Credits and usage

Successful jobs consume Gommo user credits. Check balance with POST https://api.gommo.net/ai/me (Authentication). Failed jobs may still appear in usage-history depending on upstream — do not use poll timeout as billing truth; use Gommo account APIs and dealer tools.

Common mistakes

Mistake	Fix
Wrong domain on create or poll	Same registration domain as login — Authentication
Guessed ratio / mode	Only values from POST /ai/models
Poll with wrong media	image vs video vs music
No poll after create	Job never completes on your server without wait / loop
Token in browser / mobile app	API credentials — server-side only

Next

• Quickstart — login → models → create
• Media reference — endpoints + diagram
• Common errors · Webhooks
• Models — catalog
• Integrator guide (Tier A)