A Guide to 3 Compatible Chat Completions Using a Single API Key in Node.js

MortimerNilsson7694 — Wed, 19 Aug 2026 04:33:07 +0000

Short answer: for a Node.js SaaS app that scores job candidates, use one chat-completions-shaped boundary only if every response must pass the same local schema validator before it can affect a hiring workflow. A single API key reduces credential plumbing. It does not make OpenAI, Claude, and Gemini outputs interchangeable.

Integration shape	Time to first call	Output control	Best fit
Three direct clients	More setup and config	Provider-specific handling	Teams that need each native API surface
One compatible gateway	Least application glue	One validation path, with model tests still required	A small SaaS team shipping one scoring contract
One internal adapter over direct clients	Most code to own	Maximum policy control	A platform team with provider specialists

My default for this specific workload is the middle row: one key, one narrow request interface, and one strict parser owned by the application. The parser is the recommendation, not the key. If a candidate score arrives as persuasive prose instead of the agreed object, it is unusable no matter how pleasant the integration felt.

This is a boring boundary on purpose.

The scorecard that must never ship

Benchmark the contract, not the demo. The useful comparison is whether the same candidate, rubric, request options, and validation code can travel through the integration without branching. OpenAI, Claude, and Gemini are the three model families in the test matrix; none gets a special prompt or a forgiving parser. If one needs an exception, record that exception as adapter work.

For a candidate-scoring feature, I would make the trial deliberately small and repeatable: three anonymized candidate records, one five-criterion rubric, three model targets, and two repetitions per target. That's 18 calls, which is enough to expose shape drift in an integration check without pretending to be a quality benchmark. The number is a test design proposed here, not a published performance result. Your mileage may vary, especially when the rubric contains domain language that the models interpret differently.

Use the same acceptance rule for every call. The returned value must be JSON, contain exactly the expected criterion identifiers, assign an integer score inside the rubric's declared bounds, cite only evidence present in the supplied candidate record, and include no extra keys. Record latency and request identifiers for debugging, but don't let a quick response compensate for an invalid object.

The gateway question then becomes concrete: can it preserve the fields the application needs while keeping model selection explicit? “Compatible” should mean compatible with the small interface you have tested. It shouldn't be treated as a promise that every native capability, streaming event, error shape, batch workflow, or future model option is identical. Even within one provider, asynchronous batch work is a separate operational concern from an interactive chat request; the OpenAI Batch API guide is a useful reminder that one endpoint shape cannot stand in for an entire AI platform. Put differently, the shared surface earns trust one field and one fixture at a time. A broad compatibility label doesn't get to waive a failed assertion.

Config bloat shows up early here. Three SDKs can bring three environment-variable conventions, retry defaults, release cadences, and response types into one service. A gateway can collapse that surface to a base URL and key — good — but your own interface should collapse it further to the handful of values the scoring job actually needs.

Encode rejection before choosing transport

A hiring rubric is a data contract. Treat model text as untrusted input until it crosses that contract. TypeScript types alone can't do this because they disappear at runtime; the application needs a runtime parser that rejects bad data before a score is stored or shown.

The distinction matters. A response can be valid JSON and still be wrong for the job: score: 4.5 when the rubric allows integers, a missing criterion, evidence copied from the job description rather than the candidate record, or a polished summary field nobody asked for. Loose parsing turns those errors into downstream policy. Strict parsing turns them into visible evaluation failures.

I prefer a two-stage check. First, validate the mechanical shape. Second, validate claims against application data. The second check is where generic structured-output demos usually stop being useful, because a JSON schema can constrain strings but cannot prove that a quoted sentence exists in a particular resume. That proof belongs in deterministic code with access to the source record.

Return a client-controlled status such as 422 when the model output fails this internal contract, and attach a reason code like MISSING_CRITERION or UNSUPPORTED_EVIDENCE. Those are application semantics, not claims about any model provider's HTTP behavior. They give logs and tests stable labels while model prose remains variable.

Short is good. Silent coercion isn't.

The smallest useful TypeScript boundary

The following adapter uses the common chat-completions request shape at a pseudonymous endpoint. It installs no vendor SDK and assumes the selected gateway documents this exact route and request format. The important code starts after the response: a deliberately fussy validator that accepts only the scoring object the SaaS owns.

type Criterion = {
  id: string;
  description: string;
  maxScore: number;
};

type Candidate = {
  id: string;
  evidence: string[];
};

type CriterionScore = {
  criterionId: string;
  score: number;
  evidence: string;
};

type Scorecard = {
  candidateId: string;
  scores: CriterionScore[];
};

type ChatResponse = {
  choices?: Array<{ message?: { content?: string } }>;
};

const criteria: Criterion[] = [
  { id: "typescript", description: "Production TypeScript work", maxScore: 4 },
  { id: "api-design", description: "Public API design work", maxScore: 4 },
  { id: "operations", description: "On-call or production operations", maxScore: 4 },
];

function parseScorecard(raw: string, candidate: Candidate): Scorecard {
  const value: unknown = JSON.parse(raw);

  if (!value || typeof value !== "object" || Array.isArray(value)) {
    throw new Error("INVALID_ROOT");
  }

  const record = value as Record<string, unknown>;
  const allowedRootKeys = ["candidateId", "scores"];
  if (Object.keys(record).some((key) => !allowedRootKeys.includes(key))) {
    throw new Error("EXTRA_ROOT_KEY");
  }
  if (record.candidateId !== candidate.id || !Array.isArray(record.scores)) {
    throw new Error("INVALID_SCORECARD");
  }

  const byId = new Map(criteria.map((criterion) => [criterion.id, criterion]));
  if (record.scores.length !== byId.size) {
    throw new Error("MISSING_CRITERION");
  }

  const seen = new Set<string>();
  const scores = record.scores.map((item): CriterionScore => {
    if (!item || typeof item !== "object" || Array.isArray(item)) {
      throw new Error("INVALID_CRITERION_SCORE");
    }

    const score = item as Record<string, unknown>;
    const allowedScoreKeys = ["criterionId", "score", "evidence"];
    if (Object.keys(score).some((key) => !allowedScoreKeys.includes(key))) {
      throw new Error("EXTRA_SCORE_KEY");
    }

    const criterion = typeof score.criterionId === "string"
      ? byId.get(score.criterionId)
      : undefined;
    if (
      !criterion ||
      seen.has(criterion.id) ||
      !Number.isInteger(score.score) ||
      (score.score as number) < 0 ||
      (score.score as number) > criterion.maxScore ||
      typeof score.evidence !== "string" ||
      !candidate.evidence.includes(score.evidence)
    ) {
      throw new Error("INVALID_CRITERION_SCORE");
    }

    seen.add(criterion.id);
    return {
      criterionId: criterion.id,
      score: score.score as number,
      evidence: score.evidence,
    };
  });

  return { candidateId: candidate.id, scores };
}

async function scoreCandidate(
  candidate: Candidate,
  model: string,
  signal: AbortSignal,
): Promise<Scorecard> {
  const response = await fetch("https://ai-gateway.example/v1/chat/completions", {
    method: "POST",
    signal,
    headers: {
      authorization: `Bearer ${process.env.AI_GATEWAY_KEY ?? ""}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      model,
      temperature: 0,
      messages: [
        {
          role: "system",
          content: "Return only a scorecard JSON object. Quote evidence exactly.",
        },
        {
          role: "user",
          content: JSON.stringify({ candidate, criteria }),
        },
      ],
    }),
  });

  if (!response.ok) {
    throw new Error(`UPSTREAM_HTTP_${response.status}`);
  }

  const payload = (await response.json()) as ChatResponse;
  const content = payload.choices?.[0]?.message?.content;
  if (typeof content !== "string") {
    throw new Error("MISSING_CONTENT");
  }

  return parseScorecard(content, candidate);
}

Don't copy the example domain. Replace it with a gateway route you have verified. The .example host makes that boundary explicit, while the adapter demonstrates the piece that should remain yours regardless of which upstream handles the request.

In production, keep the raw response in a restricted diagnostic store only as long as policy permits, attach the chosen model identifier and rubric version to the accepted scorecard, and separate transport retries from validation retries. A timeout may justify a transport retry. A 429 should use bounded exponential backoff with jitter and respect any documented retry hint. If an accepted scorecard is later written to storage, use an idempotency key derived from the candidate, rubric version, and scoring run so a retry cannot create a second decision. Repeating an invalid output without a fixed limit can hide a model-contract mismatch and create an unbounded queue, so classify validation errors as evidence for the model matrix rather than feeding them into the transport loop.

The same caution applies to logs. Candidate evidence may contain personal data, so operational events should carry reason codes and correlation identifiers rather than whole resumes. The scoring decision should also remain reviewable by a human; structured output correctness makes the software predictable, but it does not establish that the rubric itself is fair or that a model judgment is appropriate.

How should a Node.js SaaS app compare compatible chat completions with one API key?

Start with failure counts, not a leaderboard. For each model target, record accepted scorecards, invalid JSON, schema failures, unsupported evidence, timeouts, and other transport failures. Keep the prompt, candidate fixtures, rubric version, adapter version, and retry policy fixed. If those inputs drift between runs, the comparison says little.

Then inspect the work required around the call. Count environment values, installed packages, provider branches, request transforms, response transforms, and test fixtures. I care about those integers because each one is another place a future model change can surprise a tiny team. Still, fewer lines aren't automatically better: 40 explicit lines of validation can carry more value than a clever generic mapper nobody wants to debug at 2 a.m.

Run malformed fixtures through the parser without calling any model. Try a decimal score, a duplicate criterion, an unknown key, a fabricated evidence string, and a candidate identifier copied from another record. These tests are fast, deterministic, and more useful for release gating than asking a live model to fail on demand. One fixture should be almost right: give every criterion a valid integer but quote a sentence that appears in the job description, not the candidate evidence. That case catches a dangerous category error that pure JSON validation misses. Another fixture should repeat the same criterion three times, because checking array length without checking identifier uniqueness is a wonderfully compact way to approve incomplete work. Run the suite against the parser on every commit, then run the live 18-call matrix only when the prompt, model selection, gateway configuration, or rubric contract changes.

Bad evidence is still bad data.

For the live matrix, I'm not sure a universal pass-rate threshold exists. The acceptable bar depends on whether the score merely helps a recruiter sort a queue or automatically blocks a candidate, and the latter deserves much stricter controls than an integration article can prescribe. Decide the threshold before seeing results. Otherwise the easiest integration tends to become the winner by negotiation.

Operationally, measure cancellation, rate-limit handling, and traceability alongside output shape. Put hard request deadlines in the caller. Preserve the upstream status and request identifier when the interface supplies them. A one-key gateway reduces secret distribution, but it also creates one credential boundary, so scope it, rotate it, and keep it out of browser code.

Credential topology comes after correctness

The catch is that a compatible gateway is not suitable when the product needs a native feature that its tested common contract cannot express. Stick with direct provider clients when model-specific controls are central to the feature, when procurement requires separate provider relationships, or when the team must use a provider's native batch workflow. OpenAI's Batch API, for example, belongs in that last category; evaluate it as its own asynchronous system rather than assuming an interactive compatibility layer represents it.

This is the exit condition.

Choose the internal-adapter approach when a platform team can afford to own authentication, retries, telemetry, provider response mapping, and release tracking. It costs more engineering attention, but it keeps policy inside your boundary and permits deliberate use of native interfaces. For a company already running that platform, adding a generic gateway may create an extra layer without removing meaningful work.

Also separate chat from unrelated workloads. Speech recognition, represented by the open-source Whisper project, has different inputs and operational concerns from a candidate scorecard returned through chat completions. One key across many capabilities may be convenient, but convenience isn't evidence that they belong behind one application method.

So the decision rule stays narrow: use the gateway for this B2B SaaS scoring flow when all three targets pass the same strict fixtures and the shared interface exposes everything the flow needs. Move to direct clients or an owned adapter when the common contract starts accumulating provider switches. No product wins in the abstract. The contract either fits the job or it doesn't.