generation API health check: verify the gateway without creating a job

A health check should not create a paid generation each time a dashboard refreshes. Begin with local configuration and bounded read-only gateway checks. Report exactly what those checks establish, and keep upstream rendering availability as a separate unknown unless you have intentionally run and reviewed an authorized generation probe.

Check local configuration first

Confirm the server process has a nonempty key reference, the intended API origin, and its required database or queue connections. Log only presence and safe configuration version, never the credential value. A missing environment variable is a deployment problem that can be detected before any network request.

Keep the probe interval under your application’s request budget. A fleet of identical pods making the same read every few seconds can consume a shared key’s rate allowance even though no generation is created. Centralize expensive checks or cache their result for a short reviewed interval when appropriate.

Use the authenticated model listing narrowly

GET /api/v1/models returns registered model metadata through the same authentication wrapper used by the API. A successful result demonstrates gateway reachability, accepted credentials, and a valid model-list response. It does not contact a provider to prove a render can complete.

export async function gatewayProbe(key) {
  const response = await fetch('https://genace.ai/api/v1/models', {
    headers: { Authorization: `Bearer ${key}` },
    redirect: 'error',
    signal: AbortSignal.timeout(10000),
  });
  if (!response.ok) {
    await response.body?.cancel();
    return { gateway: 'unavailable', status: response.status };
  }
  const body = await response.json();
  return {
    gateway: Array.isArray(body.data) ? 'reachable' : 'invalid_response',
    rendering: 'not_tested',
  };
}

This is an application probe, not a dedicated Genace health endpoint. Add controlled handling for transport and parse failures in your production wrapper, and keep the HTTP status available for diagnosis.

Inspect known-job access when required

A stored job can provide a read-only check of ownership and snapshot handling. Use an identifier owned by the intended account and avoid depending on an arbitrary historical job forever without a retention plan. A NOT_OWNER response can reveal a wrong-account configuration rather than a global outage.

A job GET can advance upstream status or pending submission-failure compensation through the current service. It still does not create another generation. Choose this probe deliberately if your health model should avoid that additional processing and prefer the model list for simpler gateway checks.

Keep probe conclusions distinct

Authentication success does not prove sufficient credits, dispatch capacity, provider availability, or media download health. A local worker can be alive while new dispatch should pause. Report these dimensions separately instead of presenting a single green badge as proof every future render will succeed.

For an actual rendering canary, require an explicit budget, authorization, schedule, and operation ledger. It is not a harmless substitute for a frequent readiness probe.

Verification checklist

Test missing configuration, invalid credentials, HTTP 429, malformed JSON, and a slow gateway using local mocks. Assert no POST request occurs. Confirm the probe preserves safe diagnostics and the dashboard labels rendering as untested. Verify probe traffic itself cannot starve normal observation.

See readiness decisions, key rotation, and mock load tests.

Continue with production operations

• AI video API webhook vs polling: which one to use and when
• How to call a video generation API without blocking your agent
• generation operation unique key: deduplicate local intent without inventing API idempotency
• Browse all production operations guides