DEV Community: 煜华

How I Plan a Veo 3.1 Product Video: One Buyer Question per Shot

煜华 — Fri, 04 Sep 2026 11:30:10 +0000

When I plan an AI product video, I separate five jobs: product identity,
demonstration, atmosphere, story and the final edit. I do not put them all
into one prompt.

Here is the shot-manifest template I recommend before calling the video API.
It is a design proposal with illustrative examples, not a report of a paid
generation experiment or a customer result.

Disclosure: I work on XPLA. The XPLA fields below describe the contract I
checked against the public documentation on September 4, 2026. This is not a price, speed, access or fidelity
guarantee.

One shot owns one buyer question

“Make a premium product ad” is not a testable requirement.

“Show where the touch control is and what changes after one tap” is.

I split a sequence into:

evidence — establish product identity;
action — show one mechanism;
context — show where the product is used.

The evidence shot runs first. If the product is wrong in a restrained shot, I
do not spend more generations adding hands, moving props and dramatic camera
motion.

The manifest

type ReviewState = "draft" | "approved" | "submitted" |
  "completed" | "accept" | "repair" | "reject";

type ShotManifest = {
  shotId: string;
  role: "evidence" | "action" | "context";
  buyerQuestion: string;
  referenceMode: "frame" | "ingredient";
  mustPreserve: string[];
  allowedMotion: string[];
  prohibitedImplications: string[];
  acceptIf: string[];
  repairIf: string[];
  rejectIf: string[];
  state: ReviewState;
};

Example:

const shot: ShotManifest = {
  shotId: "sku-014-action-01",
  role: "action",
  buyerQuestion: "What does the closure look like in use?",
  referenceMode: "frame",
  mustPreserve: ["cap shape", "label geometry", "bottle color"],
  allowedMotion: ["slow hand approach", "small camera push"],
  prohibitedImplications: ["leakproof unless verified"],
  acceptIf: ["closure visible", "label readable"],
  repairIf: ["crop hides contact point"],
  rejectIf: ["cap, label or product count changes"],
  state: "approved"
};

The prompt is derived from this record. The QA decision returns to the same
record.

I enforce a motion budget

Each shot has three motion variables:

product or hand action;
camera movement;
environmental movement.

Only one gets to be high variance.

If a hand performs a precise mechanism, the camera and background stay quiet.
If the camera performs an orbit, the product stays still. This is not a model
rule; it is an application rule that makes failures explainable.

I validate the model contract separately

The current XPLA public model is veo-3.1-fast on POST /v1/videos.

Its verified wrapper accepts:

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

Reference-video input is unsupported. Google's native Veo API has a different
request shape, so I do not copy native provider fields into this wrapper.

function validateShot(s: ShotManifest) {
  const errors: string[] = [];

  if (!s.buyerQuestion.trim()) errors.push("Missing buyer question");
  if (s.mustPreserve.length === 0) errors.push("Missing product truth");
  if (s.allowedMotion.length > 2) errors.push("Motion budget too broad");

  const outcomes =
    s.acceptIf.length + s.repairIf.length + s.rejectIf.length;
  if (outcomes === 0) errors.push("Missing review rules");

  return errors;
}

A timeout is not a new creative

The API task is asynchronous. I persist the intent before submitting:

type GenerationRecord = {
  shotId: string;
  intent: "first_calibration" | "repair" | "new_creative";
  requestHash: string;
  taskId: string | null;
  state: "approved" | "submitted" | "transport_unknown" |
    "completed" | "failed";
  attempt: number;
  nextAction: "submit" | "poll" | "reconcile" | "review";
};

If the client times out, the state becomes transport_unknown. The application
reconciles the original task before creating another generation.

That distinction matters because a timeout does not prove the first task never
started.

Product QA runs before cinematic review

My review order is:

identity;
geometry and count;
label and text;
mechanism and contact points;
physical plausibility;
crop and channel fit;
lighting and rhythm.

The outcome is explicit:

accept — the shot answers its question and preserves product truth;
repair — the product is correct and a local layer can be fixed;
reject — the product, mechanism, count, label or claim changed.

A technically completed task is not publication approval.

The final ad is an edit

An eight-second generation is a production unit, not necessarily the delivery
length.

I may trim an evidence clip to two seconds, an action clip to three and a
context clip to three. Captions, approved voice, licensed sound and the CTA
belong in the editing timeline.

No paid generation was run for this article, and the diagram is a workflow
explanation—not video evidence.

The current wrapper details and request examples are in the
XPLA Veo 3.1 Fast guide.
That page currently uses noindex,follow; I am linking it for documentation,
not claiming it is indexed or ranked.

My stop rule is simple: if the first evidence shot changes a non-negotiable
product fact twice, I return to the source material instead of growing the
batch.

Before I Call GPT Image 2, I Validate These 7 Things

煜华 — Wed, 02 Sep 2026 11:45:32 +0000

I used to debug a bad AI product image by rewriting the prompt. Now I check
the request contract first.

A GPT Image 2 API request can be valid JSON and still be wrong for the selected
model. A generic UI can leak a field from another provider. Two dimension
controls can conflict. A timeout can turn one intended image into two
generations. A technically successful output can still change the product.

This is the seven-check preflight I put in front of the generation call.

Disclosure: I work on XPLA. The workflow below is an engineering pattern,
not a promise about price, access, speed or image quality.

1. Select the contract before rendering the form

I do not let one universal form submit every visible field to every image
model. The application selects a model contract first:

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

The UI should be generated from that record. A control the selected model does
not support should not appear.

2. Reject unknown fields instead of dropping them

Silently removing an unsupported field creates plausible but uncontrolled
outputs. The user chooses a setting, the backend drops it, a default is used,
and everyone blames the model.

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

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

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

  return errors;
}

An explicit local error is easier to fix than an attractive image produced
from the wrong request.

3. Make one dimension decision

An image form may expose a ratio, a pixel size, a provider-specific size field
and an orientation inferred from the prompt. I allow one supported decision:

function validateDimensions(body) {
  if (body.imageSize !== undefined) {
    return ["imageSize is not valid for this standard contract"];
  }

  const supplied = [
    body.size !== undefined,
    body.aspectRatio !== undefined
  ].filter(Boolean).length;

  return supplied > 1
    ? ["Choose size or aspectRatio, not both"]
    : [];
}

I store the requested orientation beside the output so QA can verify it.

4. Treat a reference image as a rights record

A reference is more than a URL. I store the product identity and the allowed
transformation:

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

A marketplace image being public does not automatically grant permission to
download, transform or use it in advertising.

5. Separate retries from new generations

This is the operational rule I care about most.

If a client times out, it may not know whether the server failed before or
after generation. Repeating the request can create another billable task.

Before submission, I persist:

{
  "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"
}

My state transition is:

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

submitted
  -> transport_unknown
  -> reconcile before another generation

A new creative candidate receives a new generation ID. An uncertain transport
result enters reconciliation. I do not hide both actions behind one “Try
again” button.

6. Generate one calibration image

For the first run I use:

one approved source;
one product truth sheet;
one background change;
one orientation;
one output;
one named reviewer.

The question is narrow: can the workflow preserve the product facts that
matter? More outputs do not improve the evidence if no one reviews them.

7. Review product truth, not only aesthetics

My QA table looks like this:

Check	Expected	Decision
Product count	one unit	accept / repair / reject
Body color	matte black	accept / repair / reject
Cap	silver	accept / repair / reject
Label geometry	unchanged	accept / repair / reject
Invented claims	none	accept / repair / reject
Orientation	requested ratio	accept / repair / reject
Crop safety	fully visible	accept / repair / reject

“Looks good” is not a release decision. An attractive output can still invent
a bundle, accessory, certification or quantity.

Complete preflight

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

  if (!contract) errors.push(`Unknown model contract: ${body.model}`);
  if (!body.prompt?.trim()) errors.push("prompt is required");
  if (body.n !== undefined && body.n !== 1) {
    errors.push("Use n: 1 and create separate intentional requests");
  }
  if (body.replyType !== undefined && body.replyType !== "json") {
    errors.push('replyType must be "json"');
  }

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

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

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

This is only the request boundary. A production implementation still needs
media-type, file-size, URL, privacy, account, policy and storage checks.

Failure classes need different actions

Failure class	Example	Default action
Client	empty prompt	fix locally
Contract	unsupported field	reject before submission
Access	unauthorized key	stop and fix access
Transport	lost response	reconcile before repeating
Provider	transient failure	bounded retry policy
Safety	risky request	stop or revise
Output QA	altered product	repair or reject

I keep the final order simple:

contract -> preflight -> approval -> one calibration
-> product QA -> intentional scale

The current XPLA-specific request shape and model-name boundaries are
documented in the GPT Image 2 API guide.
Recheck the live contract before production integration.

One TikTok Shop Snapshot Is Not a Trend: The Research Board I Use

煜华 — Wed, 02 Sep 2026 04:48:34 +0000

I get skeptical whenever a product-research sheet has a column called “7-day sales” but no collection window, source definition, or earlier observation.

The number may still be useful. The label is the problem.

A cumulative sales value answers, “What did this source report when I collected it?” It does not automatically answer, “What sold during the last seven days?” And one screenshot cannot tell me whether a product is accelerating.

My rule is simple:

The first collection creates a baseline. A trend requires comparable observations over time.

That sounds obvious, but it changes the whole workflow.

What I record in snapshot one

Before ranking anything, I keep source facts separate from my interpretation.

For each product I record:

collection time and time zone;
source URL and query;
market and currency;
stable product identifier;
seller, variant, bundle, color, or size when visible;
price and promotion state;
the exact name and definition of every metric;
missing fields as missing, not as zero.

I also write the research question before collecting products. “Find winners” is not a useful question. “Which home-organization products deserve a second snapshot?” is.

The narrower question gives me a defensible stopping point.

The comparability gate

Before calculating a change, I compare the two records.

They must refer to:

the same product identifier;
the same variant or bundle;
the same market and currency;
the same metric definition;
the same collection method.

If any of those changed, I do not calculate a trend line.

A similar title or image is not enough. A two-pack and a single item can share a listing concept while representing different commercial units. A promotion can change the observed price without changing the underlying product. A seller can replace a variant while keeping familiar creative.

The product identity has to survive the comparison.

What I calculate

If the observations are comparable, the arithmetic is straightforward:

snapshot_difference = later_cumulative_value - earlier_cumulative_value

But I label the output snapshot difference, not “demand,” “growth,” or “future sales.”

Why the restraint?

Because the difference may still be affected by elapsed time, reporting delay, promotion changes, listing edits, inventory, or source behavior. Two observations improve the evidence. They do not explain every cause.

For any rate, I preserve the denominator:

observed_rate = snapshot_difference / elapsed_time

I never compare a two-day interval with a fourteen-day interval as if the raw differences were equivalent.

A minimal comparison record

This is the smallest structure I find useful:

{
  "product_id": "stable-source-id",
  "market": "US",
  "currency": "USD",
  "metric_name": "sales_cumulative",
  "snapshot_1": {
    "collected_at": "ISO-8601 timestamp",
    "value": "source value"
  },
  "snapshot_2": {
    "collected_at": "ISO-8601 timestamp",
    "value": "source value"
  },
  "comparison_state": "comparable | hold | reject",
  "review_note": "what changed, what is unknown, and what happens next"
}

The important field is not the score. It is comparison_state.

An automation should be allowed to say hold when identity, policy, sourcing, or field definitions are unclear.

Data is not the final gate

I do not send every product with a positive difference into creative production.

First I check:

category and qualification requirements;
product and variant identity;
sourcing and fulfillment unknowns;
claim, brand, image, and music rights;
whether the product can be demonstrated truthfully;
whether the team has a bounded test and stop condition.

A metric can help prioritize investigation. It cannot make the product compliant, profitable, demonstrable, or suitable for an audience.

This is where human review belongs: after the comparison, before the content factory.

Turning research into a creative brief

Only an approved candidate becomes a creative brief.

I translate the evidence into:

one customer problem;
three supportable product facts;
one required demonstration;
common objections;
claims the content must avoid;
three distinct creative hypotheses;
an owner, review point, and stop condition.

Notice what is missing: “make it viral.”

The creative team needs a testable angle, not a promise.

For example, a storage product might support three honest hypotheses:

show the space problem before the product;
demonstrate the exact capacity with a fixed set of objects;
compare setup friction, without inventing a competitor.

Those are creative directions. They are not predictions of sales.

Where an API fits

An API is useful when I need repeatable queries, stable identifiers, stored timestamps, and later comparisons. It does not remove the research contract.

I still need to define:

what a field means;
which market it describes;
whether the value is cumulative;
how errors and missing data are stored;
when the workflow stops for human review.

I work on XPLA, where we document a TikTok Shop data path for product search and supported product details. The public guide explicitly keeps cumulative values separate from time-window claims:

https://xplaai.com/en-us/api/tiktok-shop-data/

That page is an implementation starting point, not a “winning product” guarantee.

The checklist I keep beside the query

Before calling a product a trend, I ask:

Do I have at least two comparable observations?
Is the product identity unchanged?
Is the metric definition explicit?
Is the elapsed time recorded?
Are missing fields still missing?
Have policy and rights been reviewed?
Is the conclusion labeled as an observation rather than a forecast?
Is a human responsible for the next decision?

If the answer to one of the first four questions is no, I do not call it a trend.

That discipline makes the research slower for a few minutes—and far more useful for every decision that follows.

AI Product Photography: The Product Truth Sheet I Use Before Prompting

煜华 — Tue, 01 Sep 2026 10:47:36 +0000

When I review an AI product photography workflow, I no longer start with a prompt like “make this look professional.”

That sentence sounds useful. It is not. It says nothing about which product details must survive, which parts may change, where the image will appear, or what would make the result unsafe to publish.

I start with a product truth sheet and one small calibration instead.

Direct answer

Do not ask an image model for a full campaign on the first run.

First, choose one image job. Record the visible and verified product facts that must not change. List what the source image does not show and what the output must never imply. Confirm rights. Then make one or two calibration images.

I only expand the set after geometry, color, logo, label text, scale, scene, and crop pass review.

This is less exciting than writing a giant cinematic prompt. It is also much easier to audit.

1. I define the image’s job before choosing a tool

“Product photo” can mean several different things:

a clean marketplace main image;
a background replacement;
a product-page lifestyle image;
an organic social post;
a paid-ad draft;
an on-model apparel image;
an early concept that will never be used as a listing.

Those jobs should not share one acceptance test.

A marketplace image may need the product to remain almost untouched. A lifestyle image can add a room, surface, prop, and atmosphere, but those additions can imply scale or usage. An apparel image must keep the garment’s construction while also handling the model, pose, anatomy, and body contact.

Before I open a generator, I write one sentence:

This image will be used for [destination] to show [one product fact or use context]. It will not be treated as [listing evidence, performance proof, or another excluded use].

If I cannot finish that sentence, I am not ready to generate.

2. I build a one-page product truth sheet

The product truth sheet is the part I wish more prompt tutorials included.

It has four sections.

Visible facts

These are details a reviewer can confirm from the approved source images:

silhouette and proportions;
visible color and finish;
logo position;
label layout;
seams, pockets, buttons, closures, ports, handles, and included parts;
the visible front, side, and back structure.

Verified facts that are not visible

These come from a current product specification or another approved source:

dimensions;
material;
capacity;
compatibility;
included accessories;
official variant and color names.

I do not add these because they “seem likely.” A plausible detail is still an invented detail.

Unknown details

This is where I record what the model is not allowed to guess:

an unseen back label;
a hidden closure;
the inside of the package;
the underside of a device;
the way a fabric behaves when worn;
a product variant with no source photo.

The word unknown does real work. It gives the reviewer permission to reject an attractive image.

Prohibited implications

I list anything the image must not quietly claim:

an unverified medical, safety, environmental, or performance benefit;
a certification that is not documented;
a before-and-after result that was never tested;
a celebrity or real person without rights;
competitor branding;
unsafe product use.

Without this sheet, “consistent” often means only “the outputs look similar to each other.” That is not the same as being faithful to the product.

3. I decide what must be preserved and what may be generated

The most useful question is not always “Which image model should I use?”

It is:

Which pixels must remain evidence, and which pixels are allowed to become creative material?

If the label, shape, or finish is important, I prefer a workflow that preserves the original product layer and changes the background, surface, shadow, or composition around it.

Regenerating the whole frame gives the model more freedom. That may be fine for a concept image. It is risky when the image will help a buyer decide what arrives in the box.

I use three rough modes:

Preserve — keep the product pixels and edit the surrounding scene.
Constrain — allow limited product edits but require a strict detail review.
Concept — allow invention, label the result clearly, and keep it away from listing evidence.

The mode belongs in the brief. It should not be guessed after the output looks good.

4. I check rights before I describe the scene

Every input has a rights question:

Who owns the product photo?
Can the brand mark be used in this channel?
Is the model authorized for this use?
Is the location or reference image licensed?
Does the intended output use fit the relevant terms?

If I create an original adult model for apparel, I do not ask the system to imitate a real person. “Make her look like this celebrity” is not a harmless style instruction.

A beautiful output does not repair a missing permission record.

5. I separate preservation rules from scene direction

I write the prompt in two blocks.

The first block protects product truth:

PRESERVE
- exact silhouette and proportions
- current navy color and matte finish
- logo position and readable label layout
- included cap and visible connector

DO NOT INVENT
- back label
- extra accessories
- certification marks
- liquid, smoke, sparks, or performance effects

The second block describes the scene:

SCENE
- clean editorial product photography
- product centered on a light stone shelf
- one folded neutral towel behind the product
- soft morning bathroom background
- realistic contact shadow
- no people, hands, text overlay, or additional products

Google’s current Product Studio guidance for its own background workflow asks merchants to describe the product, placement, surroundings, and background. I use those fields because they force the scene to become specific. I do not treat them as a universal contract for every image tool.

Vague praise—“premium,” “viral,” “luxury,” “amazing”—does not tell a reviewer what should pass.

6. I create one or two calibration images

My default is a small calibration, not a ten-image batch.

For each calibration, I record:

source-image revision;
prompt revision;
intended channel;
requested output count;
task or request count;
approved cost ceiling;
returned output;
pass, repair, or reject decision.

Then I compare the result with the product truth sheet.

The purpose is not to find one lucky image. It is to decide whether the direction is controlled enough to continue.

7. I run product QA and channel QA separately

I review the product first:

Check	What I look for
Geometry	shape, proportions, openings, handles, closures
Color	variant, tone, finish, unexpected gradients
Text	logo, label, spelling, layout, invented marks
Scale	product size relative to hands, furniture, or props
Contact	believable shadow, grip, surface contact, garment fit
Completeness	included parts present, no invented accessories

Then I review the destination:

Check	What I look for
Claim safety	scene does not imply an unverified result
Crop	important product details survive the placement
Platform fit	current format and content rules are checked
Rights	intended use matches the recorded permissions
Traceability	source, prompt, output, reviewer, and decision are stored

An API success and a publication approval are different events. I keep them separate.

8. I repair the failed layer instead of rerolling everything

If the product is right but the shadow floats, I repair the shadow.

If the scene works but the label changes, I return to the preserved product layer.

If the model invents a hidden detail, I add another source view or change the camera angle so the output does not need that detail.

Blind regeneration hides the cause of failure. It also makes it harder to tell whether a workflow is improving or just producing more attempts.

The apparel branch I verified in XPLA

I work on XPLA, so I checked its current apparel workflow before mentioning it here.

The live Fashion Street Shoot Skill is intentionally narrower than this general tutorial. It accepts one garment product photo and either an authorized adult model or an original adult model. The workflow starts with two calibration images. After approval, it expands to a 5–10 image, 3:4 street-photo set and creates a QA review page.

That is an apparel workflow. I would not use its existence to claim that XPLA supports every product category or that every output will preserve every detail. Current account access, model usage, price, and output quality still need to be checked at the time of use.

The useful idea is the gate: lock the person, garment, and visual direction with two images before paying to expand the set.

A compact checklist

Before generation:

[ ] one destination and one image job;
[ ] rights-cleared source;
[ ] visible and verified product facts;
[ ] unknown and prohibited details;
[ ] preserve, constrain, or concept mode;
[ ] one prompt revision;
[ ] task and cost ceiling.

Before expansion:

[ ] geometry passed;
[ ] color passed;
[ ] logo and text passed or have an approved repair;
[ ] scale and contact are plausible;
[ ] scene makes no unsupported claim;
[ ] channel crop and rules checked;
[ ] source, output, and decision archived.

Limitations

One source angle cannot define hidden geometry.
Generative tools can alter logos, labels, patterns, seams, reflections, hands, packaging, and scale.
A realistic scene can imply a false claim without adding any text.
Marketplace and advertising rules change.
A method that works for a bottle may fail for apparel, jewelry, reflective metal, furniture, or food.
One approved image does not prove a tool is universally “best.”
More images do not prove more clicks, orders, or revenue.

FAQ

What is a product truth sheet?

It is a short review document that separates visible facts, verified facts, unknown details, and prohibited implications. It becomes the acceptance standard for prompts and outputs.

Should I replace the background or regenerate the whole product?

If exact product details matter, preserve the product layer when possible and change the surrounding scene. Full-frame regeneration belongs in a stricter QA workflow or a clearly labeled concept stage.

How many calibration images should I create?

I usually start with one or two. The goal is to approve a direction before creating a larger set, not to search through a large batch for one lucky result.

How do I keep a logo or label accurate?

Use the clearest approved source, preserve original pixels when possible, add detail views, and compare every output with the truth sheet. Reject or repair altered text rather than explaining it away.

Can one source photo support a full lifestyle set?

Sometimes, but only for what the source actually shows. If a new angle reveals hidden geometry, provide another view or avoid that angle.

Does a technically successful output count as approved?

No. Technical completion only proves the request finished. Product truth, rights, claims, crop, and channel fit still need review.

Sources and disclosure

Google Merchant Center: About Product Studio, rechecked September 1, 2026. I use its scene fields as a bounded example, not a universal tool contract.
XPLA: Fashion Street Shoot Skill, rechecked September 1, 2026.

Disclosure: I prepared this article for XPLA. I verified the live page and current repository wording, but I did not invent a paid run, customer result, sales lift, traffic result, or tool ranking.

If your product is apparel, the live XPLA page shows the narrower one-garment, two-calibration, approve-then-expand workflow:

https://xplaai.com/skills/xpla-fashion-street-shoot

Unified AI API Tutorial: Keep Model Contracts Explicit

煜华 — Tue, 01 Sep 2026 06:41:49 +0000

Why I wrote this

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.

This guide shows 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.

Application job	XPLA route	Pattern
Discover models available to a token	`GET /v1/models`	synchronous JSON
Generate or edit an image	`POST /v1/images/generations`	synchronous for supported contracts
Create a video task	`POST /v1/videos`	asynchronous
Check a video task	`GET /v1/videos/{task_id}`	poll by task ID
Retrieve completed video content	`GET /v1/videos/{task_id}/content`	authenticated content read
Run a chat completion	`POST /v1/chat/completions`	completion or streaming contract
Generate speech	`POST /v1/audio/speech`	text-to-speech contract
Search TikTok Shop data	`GET /v1/tiktok/shop/search`	commerce-data query
Get one TikTok product	`GET /v1/tiktok/product`	product lookup
Parse an authorized public video	`POST /v1/video/parse`	public-video analysis

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:

its exact public name;
the endpoint family it belongs to;
the accepted fields;
whether the result is synchronous or asynchronous;
the last contract-review date;
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:

send POST /v1/videos;
persist the returned task ID;
poll GET /v1/videos/{task_id} with bounded intervals;
stop polling on a documented terminal state;
retrieve ready content through GET /v1/videos/{task_id}/content;
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.

Signal	Application action	Avoid
`401`	stop and request a valid server-side token	sending the key to client analytics
`400` or validation error	show the rejected field and selected contract	retrying the same invalid body
`429`	use bounded backoff and show availability state	unlimited concurrent retries
terminal task failure	preserve task ID and reason	reporting success because task creation returned an ID
authenticated or temporary content URL	retrieve through the documented flow	treating it as a permanent public asset
unsupported region or account	disable the action and explain the requirement	implying universal availability

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.

Related resources

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.