New gateway (source guide)

Gateway migration

OneAster Gateway deployed revision f09a2d5 and Go build 7ba12de+oneaster.0.1.0 contract and API guide.

Migrating from legacy Core to Gateway (7ba12de+oneaster.0.1.0)

This page compares legacy Core 0.46.2 with deployed oneaster-gateway commit f09a2d5da1c9b6fbfd95ae4246080a8489d44564 (production version 7ba12de+oneaster.0.1.0). The legacy Core OpenAPI (/api-reference/core-0462-openapi.json) and historical integration guides are retained strictly as historical references; current home pages, guides, and API reference pages document the active gateway protocol. Matching path names do not imply identical request schemas, response envelopes, billing rules, or task lifecycles.

Inference, audio, and async task changes

GET /v1/models and POST /v1/chat/completions keep their paths, but callers must pass the callable model ID (model_name / id) rather than display_name. Image editing uses POST /v1/images/edits (or logged-in POST /pg/images/edits) and supports PR #46 extension fields complexity, markup, svg, frame_count, and frame_duration_ms.

Legacy POST /v1/tasks is replaced by plugin-scoped POST /v1/tasks/kie (and logged-in POST /pg/tasks/kie); legacy GET /v1/tasks/{id}/content is replaced by listing GET /v1/tasks/{id}/artifacts (or GET /pg/tasks/{task_id}/artifacts) and downloading each track via GET /v1/tasks/{id}/artifacts/{artifact_key}/content (or GET /pg/tasks/{task_id}/artifacts/{artifact_key}/content) with Authorization: Bearer. There is no /v1/audio/generations route family: synchronous TTS and STT use /v1/audio/speech, /v1/audio/transcriptions, and /v1/audio/translations (plus /pg/audio/*), while KIE Suno music generation uses async tasks on POST /pg/tasks/kie (model: "ai-music-api/generate", returning two MP3 tracks per task).

Legacy Core Responses storage, previous_response_id continuation, and DELETE /v1/responses/{id} are not migrated. Legacy task IDs, historical media URLs, PNG archives, and unsettled records cannot be replayed across systems. Task status UNKNOWN means outcome or billing is still unconfirmed, not failed or refunded; inspect GET /oneaster/v1/task-diagnostics/{task_id} for funding source, registration status, and settlement_receipt instead of automatically retrying.

Accounts, wallet, and Session Playground changes

Legacy /core/v1/* account, wallet, text-capacity, and Core 0.40 Playground routes are retired. Use native /api for login and security (including PR #49 Google native OAuth login via POST /api/oauth/state and POST /api/oauth/google), /oneaster/v1 for account, wallet, Keys (/oneaster/v1/keys), model catalog, task diagnostics, and billing (including PR #48 unified billing preview GET /oneaster/v1/billing/preview and PR #47 Stripe top-ups and credit records), /pg for logged-in wallet Playground calls (with Idempotency-Key persistence and GET /pg/requests/by-intent + GET /pg/requests/{request_id} recovery), and /v1 for personal inference API Key calls. Legacy Core sessions cannot replace a native access_token; never duplicate orders or generation requests after uncertain outcomes.