AI Relay

Authenticate with your application API key or login session. The Relay site key stays on the server.

1. Call GET /api/ai/models and select a permitted model/specification with enabled: true. Only the Nano Banana family (nano-banana, nano-banana-2, nano-banana-pro) is exposed; other IDs are rejected on submission. Discovery does not guarantee provider availability.
2. Persist an Idempotency-Key of 8–200 printable characters alongside the original request before submitting. Every retry uses the same key and body.
3. Submit to POST /api/ai/image/generate or POST /api/ai/video/generate with provider: "ai-relay", the discovered model, prompt, resolution, numOutputs: 1, and watermark: false. Video also requires a discovered integer duration.
4. Keep the returned application taskId; poll GET /api/ai/tasks/{id} at intervals of at least pollAfterSeconds. Polling never submits a generation.
5. For status: 1, download outputImageUrls / outputVideoUrl through the returned application URLs. Downloads require your application API key or same-origin session cookie. Video supports one byte Range.

Reference images, arbitrary parameters, callbacks, client identity fields, multiple outputs and video watermarking are rejected. Requests without provider: "ai-relay" retain the existing provider flow.

SUBMISSION_UNKNOWN means acceptance could not be confirmed. Replay only the original POST with its original key/body. RECONCILING and FINALIZING remain pending even with an error code. Browser cancellation or timeout only ends that wait; resume the same task later.

The application taskId identifies a saved business request; it can exist before Relay has acknowledged an upstream task. If status: 0, submissionUncertain: true and no providerTaskId are returned, recover with the saved POST/key/body. Once providerTaskId exists, only poll the original application task. An expired or terminal task must never trigger another automatic submission.

The Nano Banana, Nano Banana 2 and Nano Banana Pro pages use this same Relay playground. Their model selection comes from authenticated discovery, preserves the selected model across login, and does not silently substitute a different model if the requested one is unavailable. Resuming a saved request remains possible after the initial credit debit, even when the remaining balance cannot fund a new request.

SUCCEEDED, FAILED and CLOSED_UNKNOWN are terminal. A budget rejection returns HTTP 429 with a saved task snapshot; keep its taskId. Confirmed FAILED tasks receive the application's customer-credit refund once. Unknown closures, conflicts and expired/unavailable tasks require manual reconciliation and do not automatically refund credits. This is separate from any Relay/supplier billing.

Media expires after 30 days. HTTP 404/410 never authorizes automatic regeneration. Result URLs are private, not permanent public CDN links.

Operators configure AI_RELAY_BASE_URL / AI_RELAY_SITE_KEY on the server and apply database migrations. pnpm relay:check performs health/model GET requests only, without generation.