That was too optimistic.

An API documentation page has at least two jobs:

1. answer a developer’s first question quickly; and
2. provide an interface for exploring the details.

JavaScript is excellent for the second job. It is a fragile place to hide all of the first.

My current rule is simple:

The server response must contain the stable answer. JavaScript may enhance it, but it should not be required to discover what the page is about.

This is not a claim that client-rendered pages cannot be indexed. Search engines can process JavaScript. It is an engineering decision to make the essential information usable by more readers, crawlers, link unfurlers and failure modes.

The six-field server HTML contract

For every model page, I now expect the initial HTML to answer six questions:

If I remove the scripts and cannot answer those questions, the page is not finished.

The server output does not need every interactive control or every parameter row. It needs the stable facts that make the URL meaningful.

Here is the kind of structure I want in the response:

<main>
  <nav aria-label="Breadcrumb">
    <a href="/docs">Model docs</a>
    <span>Gemini 3.1 Pro</span>
  </nav>

  <article>
    <h1>Gemini 3.1 Pro</h1>
    <p>
      Model documentation with the request endpoint,
      model identifier and implementation constraints.
    </p>

    <dl>
      <dt>Endpoint</dt>
      <dd><code>POST /v1/chat/completions</code></dd>

      <dt>Model ID</dt>
      <dd><code>gemini-3.1-pro</code></dd>
    </dl>

    <a href="/docs">Compare other model docs</a>
  </article>
</main>

The exact values above must come from the product’s verified documentation or implementation. I never fill gaps with plausible model names.

Why I separate the answer from the interface

Interactive documentation tends to accumulate dependencies:

• a JavaScript bundle;
• a router;
• authentication state;
• a syntax highlighter;
• a request builder;
• analytics;
• sometimes a live model call.

Any one of those can fail while the underlying documentation is still perfectly useful.

I therefore divide the page into two layers.

Layer 1: the stable answer

This is server-rendered:

• one descriptive H1;
• a short, specific summary;
• verified request coordinates;
• the few constraints needed to avoid a bad first request;
• normal HTML links to parent and related pages.

Layer 2: the working surface

This is enhanced with JavaScript:

• parameter controls;
• copy buttons;
• language tabs;
• request examples;
• authentication-aware actions;
• live task status.

The second layer is allowed to be dynamic because the first layer already explains the page.

I do not render a keyword list

Server rendering is not a license to produce a wall of near-duplicate search phrases.

I write for one primary task. A model page can naturally mention its API, endpoint, model identifier and main capability because a developer needs those details. It should not repeat every possible variation of “best AI API” or create dozens of thin country copies.

My editing test is:

Would this sentence still deserve to exist if search engines did not?

If the answer is no, I cut it.

That test also helps with AI answer systems. A concise definition, a small table and a checkable procedure are easier to quote accurately than a long paragraph of promotional claims. That does not guarantee citation. It simply makes the source less ambiguous.

The detail URL must fail honestly

One mistake I see in documentation SPAs is returning a generic 200 page for every unknown route.

For a missing model document, I want:

• HTTP 404;
• a clear “document not found” message;
• no accidental canonical to a valid model;
• a useful link back to the docs index.

A soft 404 wastes both reader attention and crawl attention. More importantly, it makes automated QA harder because a broken link appears successful.

I include one malformed URL in every release check:

curl -I "https://example.com/docs/not-a-real-model"

The test passes only when the response is genuinely missing, not when the application renders a friendly error inside an HTTP 200 shell.

My release checklist

I use two views of the same page.

1. Inspect the raw response

curl -sS "https://example.com/docs/model-name" > response.html

Then I check:

rg -n "<title|<h1|canonical|Model ID|Endpoint" response.html

This catches the most common regression: the browser looks fine, but the facts exist only after JavaScript runs.

2. Use the page as a reader

I open the rendered page and check:

• the H1 is visible and unique;
• the summary matches the page;
• code is readable on mobile;
• copy buttons do not replace selectable text;
• links work without custom click handlers;
• the interactive example is clearly separated from the factual reference.

I also check the docs index. A perfect detail page is still difficult to discover if no crawlable page links to it.

A real implementation boundary

On XPLA’s model documentation, I applied this split to the public docs index and model pages. The initial response contains the page identity and stable model facts; the client interface keeps the richer parameter and example experience.

You can inspect the model documentation index and a Gemini 3.1 Pro documentation page. Those links are examples of the structure, not evidence of guaranteed ranking or traffic.

The useful part of this pattern is that it scales as the model catalog changes:

• content fields have an explicit contract;
• interactive components can evolve independently;
• missing routes can be tested;
• every release can be verified from the outside.

What I would not do

I would not:

• render only a title and call the page “SEO-ready”;
• place a huge hidden copy of the client interface in the HTML;
• create one URL per keyword synonym;
• use a canonical tag to disguise duplicate community posts;
• publish unverified model IDs or capabilities;
• promise that server rendering creates rankings or AI citations.

The goal is not to manufacture more indexable text. The goal is to make each useful URL contain a complete, honest first answer.

Frequently asked questions

Do API docs need full server-side rendering?

Not always. Static generation, server rendering and carefully designed pre-rendering can all work. I care about the resulting response: the stable answer and links should be present without depending on client-side execution.

Should every parameter be in the initial HTML?

No. Put the fields needed to identify and start evaluating the API in the initial response. Large parameter explorers can remain interactive, provided essential facts are not hidden inside them.

Does this guarantee Google or Bing indexing?

No. Indexing and ranking depend on many signals. This pattern improves accessibility and reduces rendering dependencies; it is not a ranking guarantee.

Does it guarantee inclusion in AI answers?

No. Clear definitions and checkable facts may make a page easier to interpret, but no publisher can promise citation by an AI system.

What should I test first?

Fetch the raw HTML for one important detail page. If its H1, summary, endpoint, model ID and a parent link are missing, start there.

Sources

• Google Search Central: JavaScript SEO basics
• Google Search Central: Make your links crawlable

Disclosure: I work on XPLA. The checklist is the process I use; the XPLA links are implementation examples.

The problem is not only output quality. A large prompt produces a large failure surface.

My proposed shot queue gives every item one buyer question and one terminal review decision. The schema is an illustrative design, not a production benchmark or a report of a paid generation experiment.

I work on XPLA. The contract details below describe the XPLA wrapper checked against public documentation on September 4, 2026, not Google's native API and not a price, speed, access or fidelity guarantee.

Queue schema

type ShotRole = "evidence" | "action" | "context";
type ReviewDecision = "accept" | "repair" | "reject";

type ShotJob = {
  shotId: string;
  sku: string;
  variant: string;
  role: ShotRole;
  buyerQuestion: string;
  referenceMode: "frame" | "ingredient";
  references: Array<{
    assetId: string;
    rights: "approved" | "hold";
    proves: string[];
  }>;
  mustPreserve: string[];
  allowedMotion: string[];
  prohibitedImplications: string[];
  acceptIf: string[];
  repairIf: string[];
  rejectIf: string[];
};

The shot cannot enter approved while:

• its buyer question is empty;
• a reference is on rights hold;
• the variant is ambiguous;
• mustPreserve is empty;
• no review criteria exist.

Three roles, three failure surfaces

An evidence shot establishes identity. It keeps the product visible and motion restrained.

An action shot demonstrates one mechanism or interaction.

A context shot supplies the environment and use case.

The order matters. I review evidence before action and action before atmosphere. A wrong product in a beautiful context shot is still a wrong product.

Motion budget

I classify motion as:

type MotionPlan = {
  productOrHand: "none" | "low" | "high";
  camera: "none" | "low" | "high";
  environment: "none" | "low" | "high";
};

The application allows no more than one high.

function validateMotion(plan: MotionPlan) {
  const highCount = Object.values(plan)
    .filter(value => value === "high").length;

  return highCount <= 1
    ? []
    : ["Use only one high-variance motion source per shot"];
}

This is not a model restriction. It is a debugging restriction. If the hand, camera and environment all move aggressively, a failed mechanism becomes hard to diagnose.

Wrapper contract gate

The current XPLA model name is veo-3.1-fast and the route is POST /v1/videos.

The inspected wrapper accepts:

• fixed eight-second tasks;
• 720p or 1080p;
• 16:9 or 9:16;
• frame mode with up to two ordered image references;
• ingredient mode with up to three references.

It rejects reference-video input. Native Google Veo documentation may describe capabilities or fields that do not belong in this wrapper.

The queue validates its access-layer contract before submission:

function validateReferenceCount(job: ShotJob) {
  const max = job.referenceMode === "frame" ? 2 : 3;

  if (job.references.length > max) {
    return [`${job.referenceMode} mode accepts at most ${max} references`];
  }

  if (job.references.some(ref => ref.rights !== "approved")) {
    return ["Every reference must pass the rights gate"];
  }

  return [];
}

State belongs to the shot intent

The generation record is separate from the creative brief:

type TaskState =
  | "approved"
  | "submitted"
  | "transport_unknown"
  | "completed"
  | "failed"
  | "reviewed";

type GenerationTask = {
  shotId: string;
  generationIntent: "first_calibration" | "repair" | "new_creative";
  requestHash: string;
  taskId: string | null;
  state: TaskState;
  attempt: number;
  nextAction: "submit" | "poll" | "reconcile" | "review";
};

A transport timeout moves the record to transport_unknown. It does not change generationIntent to new_creative.

The application reconciles the original task before creating another paid intent. Otherwise one ambiguous retry can become two valid outputs with no obvious explanation.

QA before editing

My review order is:

1. SKU and variant identity;
2. geometry and product count;
3. label and text;
4. mechanism and contact points;
5. physical plausibility;
6. crop and channel fit;
7. lighting and rhythm.

The output becomes:

type Review = {
  shotId: string;
  decision: ReviewDecision;
  failedChecks: string[];
  repairScope: string[];
  reviewer: string;
  reviewedAt: string;
};

repair is deliberately narrow. It fits cases where the product is correct and a local layer—crop, timing, caption or sound—can be fixed.

If the label, count, mechanism or product geometry changed, the decision is reject.

Editing is a different stage

An eight-second model task is a production unit, not necessarily the final ad.

The editing stage may trim approved clips, add verified captions, place an approved voice track and licensed sound, and assemble the final sequence.

It should also preserve lineage:

source asset -> shot card -> normalized request -> task ID
             -> review decision -> timeline clip

No paid generation was run for this article. The schema and diagram explain a workflow; they are not output-quality evidence or a customer case.

The current fields and limitations are documented in the XPLA Veo 3.1 Fast guide. That English documentation page currently returns noindex,follow; this link is for readers, not a claim of indexation or ranking.

My stop rule: after two evidence-shot failures on the same non-negotiable product fact, return to the source and shot design. Do not scale the queue.

I saw why a normal “retry” button is too vague for a GPT Image 2 API workflow: a timeout tells the client that the result is unknown. It does not prove that no generation happened.

So I model generation as a small state machine and put contract validation in front of it.

I work on XPLA. This is the application-layer pattern I use, not an independent product comparison or a price, latency, access or fidelity guarantee.

State belongs to the intent, not the HTTP attempt

I persist the record before submitting:

{
  "generation_id": "img-job-20260902-001",
  "intent": "new_calibration",
  "request_hash": "sha256-of-normalized-request",
  "state": "submitted",
  "attempt": 1,
  "result_state": "unknown",
  "next_action": "check_before_repeating"
}

Then I use explicit transitions:

draft -> approved -> submitted -> completed
completed -> accepted | repair | rejected

submitted -> transport_unknown
transport_unknown -> reconcile
reconcile -> completed | safe_retry | manual_review

An intentional second creative gets a new generation ID. A transport retry keeps the original intent. This makes duplicates visible in logs and billing review instead of turning them into mysterious extra outputs.

Contract validation happens before state submission

The form is driven by a contract registry:

const contracts = {
  "gpt-image-2": {
    endpoint: "/v1/images/generations",
    allowed: new Set([
      "model", "prompt", "image", "images",
      "size", "aspectRatio", "quality", "replyType", "n"
    ]),
    forbidden: new Set(["imageSize"])
  }
};

I reject unknown fields rather than deleting them:

function validateFields(body, contract) {
  const errors = [];

  for (const key of Object.keys(body)) {
    if (!contract.allowed.has(key)) {
      errors.push(`Unsupported field: ${key}`);
    }
  }

  for (const key of contract.forbidden) {
    if (body[key] !== undefined) {
      errors.push(`Forbidden field: ${key}`);
    }
  }

  return errors;
}

Silent deletion makes debugging harder because the UI says one thing while the submitted request says another.

One request gets one dimension decision

I validate dimensions separately:

function validateDimensions(body) {
  if (body.imageSize !== undefined) {
    return ["imageSize does not belong to this standard contract"];
  }

  if (body.size !== undefined && body.aspectRatio !== undefined) {
    return ["Choose size or aspectRatio, not both"];
  }

  return [];
}

I also persist the selected orientation with the job. Otherwise the reviewer cannot distinguish a model failure from a request-builder failure.

Reference inputs carry rights and product facts

The job owns a companion record:

{
  "source_type": "merchant_upload",
  "rights_state": "confirmed_for_internal_calibration",
  "sku": "merchant-sku-104",
  "variant": "matte-black-500ml",
  "must_preserve": [
    "one unit",
    "matte black body",
    "silver cap",
    "label geometry"
  ],
  "allowed_changes": ["background", "surface", "lighting"]
}

The generation cannot move to approved if rights or exact product identity are unresolved. A public listing photo is not automatically licensed for AI transformation.

Calibration is a state, not a batch size

My first approved run has one source, one output and one reviewer. The result moves to:

• accepted when the product facts and release criteria pass;
• repair when a bounded change can fix the job;
• rejected when rights, contract expectations or product truth fail.

The QA record checks count, color, label, claims, orientation and crop. A visually impressive output can still be commercially unusable.

Failure ownership

Collapsing these into one failed state removes the information needed for the next safe action.

The boundary I ship

function preflight(body, rightsRecord) {
  const contract = contracts[body.model];
  const errors = [];

  if (!contract) errors.push(`Unknown model: ${body.model}`);
  if (!body.prompt?.trim()) errors.push("prompt is required");
  if (body.n !== undefined && body.n !== 1) {
    errors.push("Create a separate intent for each candidate");
  }
  if (body.replyType !== undefined && body.replyType !== "json") {
    errors.push('replyType must be "json"');
  }

  if (contract) {
    errors.push(...validateFields(body, contract));
    errors.push(...validateDimensions(body));
  }

  if ((body.image || body.images) &&
      rightsRecord?.rights_state !== "confirmed_for_internal_calibration") {
    errors.push("Reference rights are not confirmed");
  }

  return { ok: errors.length === 0, errors };
}

It is not a universal SDK. I add file, URL, privacy, policy, account and storage validation around it.

The useful order is:

contract -> preflight -> approved intent -> submitted
-> reconcile if unknown -> one calibration -> product QA -> scale

For the currently exposed XPLA request shape, see the GPT Image 2 API guide. Verify the live model contract again before a production integration.

When I review a unified AI API, I do not start by counting model names. I start by checking which contracts are explicit, which jobs are asynchronous, and where the application must keep its own validation and review gates. This is the contract-first checklist I use to separate a useful access layer from a misleading "one schema for everything" abstraction.

Direct answer

A useful unified AI API gives your application one access layer without pretending that every model behaves the same.

Centralizing the account, base URL, authentication pattern, and route discovery can reduce integration overhead. But image, video, speech, chat, and commerce tasks still have different parameters, response patterns, and review requirements. A reliable implementation keeps those contracts explicit.

In this guide, I show a contract-first workflow using XPLA's documented route families as the example. The method also applies when you are designing your own multi-model gateway.

What should a unified AI API actually unify?

The word unified is useful when it describes:

• one account and access layer;
• one base URL;
• one Bearer-token pattern;
• one place to discover current models;
• explicit routes for different task families;
• a consistent place to check current documentation.

It becomes misleading when it implies:

• one universal request body;
• identical model parameters;
• identical synchronous or asynchronous behavior;
• a fixed catalog available to every account;
• guaranteed failover, lower cost, latency, throughput, or uptime.

The safest architecture unifies access while preserving model contracts.

1. Define the application job before choosing a model

Start with the result your user needs:

• What is the input?
• What output must be delivered?
• Is a response needed immediately?
• Can the task run asynchronously?
• Does the task contain private media?
• What rights and retention rules apply?
• What must a human review before the result is used?

This decision should select a route family before it selects a model name.

The table is a route-selection aid, not a guarantee that every model is enabled for every account. Check the current documentation before implementation.

2. Discover models instead of copying an old model name

Keep the real API key outside source code, screenshots, browser JavaScript, and shared prompts. In a server-side shell, assign it to an environment variable:

export XPLA_API_KEY="replace_with_your_key"

curl --request GET \
  --url https://xplaai.com/v1/models \
  --header "Authorization: Bearer $XPLA_API_KEY"

Treat the response as a current capability input, not a permanent catalog. Before you expose a model in your product, record:

1. its exact public name;
2. the endpoint family it belongs to;
3. the accepted fields;
4. whether the result is synchronous or asynchronous;
5. the last contract-review date;
6. the output checks required by your application.

Do not silently replace one model with another when their parameters differ.

3. Build a model-contract registry

A route adapter should not accept every possible field and forward it blindly. Instead, keep an explicit registry:

type ModelContract = {
  route: '/v1/images/generations' | '/v1/videos';
  allowedFields: readonly string[];
  result: 'synchronous' | 'asynchronous';
  reviewedAt: string;
};

const contracts: Record<string, ModelContract> = {
  'gpt-image-2': {
    route: '/v1/images/generations',
    allowedFields: ['model', 'prompt', 'size', 'images', 'quality'],
    result: 'synchronous',
    reviewedAt: '2026-08-31',
  },
  'veo-3.1-fast': {
    route: '/v1/videos',
    allowedFields: [
      'model',
      'prompt',
      'seconds',
      'resolution',
      'ratio',
      'images',
      'metadata',
    ],
    result: 'asynchronous',
    reviewedAt: '2026-08-31',
  },
};

This is an illustrative registry based on a dated contract review. Generate production values from the documentation and tests your team has actually approved.

The review date should trigger revalidation. It is not decorative metadata.

4. Separate synchronous results from asynchronous tasks

Supported image-generation contracts can return a result in the initial response. Video creation requires a task lifecycle:

1. send POST /v1/videos;
2. persist the returned task ID;
3. poll GET /v1/videos/{task_id} with bounded intervals;
4. stop polling on a documented terminal state;
5. retrieve ready content through GET /v1/videos/{task_id}/content;
6. send the output to rights and quality review.

Do not keep a task ID only in browser memory. A refresh, worker restart, or temporary network failure should not make the application lose the job.

5. Normalize errors without erasing the original cause

Your product can present a small internal error taxonomy, but preserve the original route, public model name, status, and task ID.

A gateway does not remove upstream or model failure modes. It gives the application one public access boundary from which to handle them.

6. Add observability before adding more models

For each request, consider recording:

• an internal request ID with no customer secret;
• route and public model name;
• timestamp and application version;
• an input hash instead of private raw media where possible;
• task ID for asynchronous work;
• current state and terminal reason;
• output location and retention policy;
• retry count;
• review decision.

Do not log a full authorization header, API key, private signed URL, or unrestricted customer prompt by default.

7. Treat API success and production approval as separate gates

A 200 response or a completed task proves that the technical request finished. It does not prove that:

• product identity is accurate;
• text and claims are correct;
• the media is licensed for its intended use;
• the result fits the destination platform;
• retention and privacy requirements were met.

Merchant image and video workflows need a second approval gate for product truth, rights, output quality, and storage.

When should you use an API instead of a packaged workflow?

Use the raw API when your team wants to own:

• the user interface and database;
• the contract registry;
• task queues and retry behavior;
• storage and retention;
• approvals and cost controls;
• output QA and support.

Use a packaged Commerce Skill when you want a repeatable workflow that coordinates multiple steps and reports its evidence and approval gates. A Skill does not eliminate model cost, rights review, or human judgment; it changes how the workflow is organized.

Limitations to plan for

• One key does not mean one schema.
• Not every route is OpenAI-compatible.
• Model lists and account availability can change.
• Route registration does not prove every account can use every model.
• Price, credits, latency, throughput, and uptime need current first-party checks.
• Generated or parsed media still needs rights and output review.
• A unified API does not guarantee lower cost or better reliability.

FAQ

What does “unified AI API” mean?

It means that selected task families share an access layer, base URL, authentication pattern, and route-discovery process. It should not mean that all models use one body or response schema.

Does every endpoint use one request format?

No. Image, video, speech, chat, and commerce routes have separate contracts. Validate only the fields documented for the selected model and route.

Is every XPLA route OpenAI-compatible?

No. The chat route follows the Chat Completions contract. Do not apply one global compatibility assumption to image, video, speech, or commerce routes.

How should an application handle video generation?

Persist the task ID, poll at bounded intervals, stop on a terminal state, and retrieve content through the documented authenticated route.

Does a unified API guarantee lower cost or higher uptime?

No. Those claims require current pricing and controlled operational evidence. An access layer alone cannot prove them.

Media plan

This tutorial uses one original 1200×630 architecture diagram rather than a fabricated product screenshot. The PNG has been losslessly optimized and contains no customer data, credential, private URL, or generated UI claim.

Internal links

• Unified AI API guide — maintained route guide
• AI image generation API — image route details
• AI video API — asynchronous video lifecycle
• Commerce Skills — packaged workflow alternative

CTA

Read the maintained XPLA unified AI API guide and choose the route before creating one small contract test.

Disclosure: I prepared this tutorial for XPLA after rechecking the maintained guide and route contracts on September 1, 2026. I have not included a paid result, customer case, traffic claim, or ranking promise.