I started 3Stone AI because the work I wanted to do rarely ended in one format. Research might need to become a brief, a presentation, or a spreadsheet. An image might become a video. A plan might need to become an interactive tool. I wanted research, media generation, editable Office files, and useful software available through one product and one API instead of making the customer assemble a chain of unrelated services.
At first, that sounds like an interface problem: put several models behind a chat box and route each request to the right provider. Building the real product taught me that routing is only the beginning. The harder work is making every accepted request produce a result the customer can actually open, use, download, revisit, and revise.
Real customer problems forced that lesson repeatedly. A request could pass automated tests while the customer journey still broke. Audio could exist but be the wrong kind of audio. An entitlement could be correct in one system and stale in another. A provider could report success while the exported file was unusable. I stopped treating “the test passed” as the finish line. I began requiring evidence from the delivered output and the complete customer journey.
One API still needs capability-specific contracts
Different kinds of work do not become identical merely because they share authentication. Research can complete synchronously and return sources. Image or Office generation may require a durable background job. A spreadsheet is not successful because a ZIP of XML exists; it must open in Excel, preserve formulas, and remain editable. A retry after a network timeout must not submit the provider job twice or charge twice.
The current 3Stone developer contract therefore uses capability-specific endpoints behind common authentication, idempotency, usage, job, and artifact conventions. Certified public routes include chat, research, image analysis, image generation, editable PowerPoint, Excel and Word generation, music, and interactive tools. Video exists in the customer product, but it is not presented as a public API capability until the external lifecycle meets the same certification standard.
That boundary matters. A useful API should describe what developers can verify today, not everything an internal product can theoretically attempt.
Make asynchronous work explicit
Long-running AI work creates an awkward interval: the provider may have accepted a paid job even when the HTTP response never reaches you. Retrying blindly can create two jobs. Reporting failure immediately can also be wrong.
We use durable request and job identities, save provider receipts as early as possible, and separate states such as accepted, running, completed, failed, and reconciliation required. The customer polls the 3Stone job rather than learning each provider's lifecycle.
A simplified image request looks like this:
const base = "https://one.3stoneai.com";
const idempotencyKey = crypto.randomUUID();
const submitted = await fetch(`${base}/v1/images`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.THREESTONE_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({
prompt: "An editorial photograph of a solar-powered neighborhood library at sunrise; no text or logos."
}),
});
const job = await submitted.json();
if (submitted.status !== 202) throw new Error(job.error?.message ?? "Request rejected");
while (true) {
await new Promise(resolve => setTimeout(resolve, 2500));
const response = await fetch(`${base}/v1/jobs/${job.job_id}`, {
headers: { Authorization: `Bearer ${process.env.THREESTONE_API_KEY}` },
});
const current = await response.json();
if (current.status === "completed") break;
if (["failed", "reconciliation_required"].includes(current.status)) {
throw new Error(`Job ended as ${current.status}`);
}
}
The important details are not glamorous: bearer keys stay on the server, every mutating request has a unique idempotency key, accepted asynchronous work returns a durable job ID, and ambiguous provider outcomes are reconciled instead of automatically replayed.
A fallback must support the same job
One recurring integration mistake was treating any available model as a fallback. It is not enough for two providers to share an output label such as “image” or “video.” A text-to-image endpoint may not edit an image. A text-to-video endpoint may not replace a character in existing footage. A video endpoint that returns silent footage cannot honestly claim synchronized audio.
That changed how I think about recovery. A fallback is eligible only when it supports the requested inputs, preservation behavior, output format, and practical limits. It also must be safe for the particular failure. A known authentication rejection before execution is different from a connection loss after a provider may have accepted a paid request.
For image generation, 3Stone's separate-provider fallback is constrained to confirmed operational failure classes. It does not activate for moderation decisions, ambiguous post-submission failures, or arbitrary errors. For video, audio routing distinguishes source audio, ambience and effects, dialogue, music, narration, and intentional silence. ElevenLabs can be a recovery option for appropriate speech; it is not automatically attached to every video.
The broader lesson is simple: recovery that changes the customer's request is not recovery.
Validate the artifact, not the provider status
The defect pattern that most changed my release standard was seeing technical success without a usable customer outcome. A provider could say “succeeded,” a route could return HTTP 200, and a test suite could be green—yet the file might not open correctly, the audio might be irrelevant, or the next customer action might fail.
Now I want evidence at the artifact boundary. Images must decode and meet the expected dimensions. Videos are probed for duration, codec, dimensions, and required audio. PowerPoint, Excel, and Word files are reopened and checked for their native structure, including slides, sheets, formulas, tables, and editability. Interactive HTML is rendered and exercised. Customer certification includes creation, preview or playback, download, persistence, reopen, and revision where the capability supports it.
This standard also applies to account and entitlement work. A deletion button is not verified because it displayed a confirmation dialog; the customer must return to signed-out state and the intended account data must actually be gone. A microphone permission prompt is not proof of a live voice session; the system needs a real captured turn, an audible response, interruption behavior, transcript persistence, and correct accounting.
Idempotency is a billing promise
Idempotency is often described as an API convenience. For paid AI work, it is also a billing guarantee.
Each mutating request binds the caller's idempotency key to a fingerprint of the operation. The same key with the same request returns the original outcome. The same key with changed input is rejected. Before expensive execution, the system reserves a bounded allowance. Completion settles recorded usage. Known pre-execution failure releases the reservation. An ambiguous provider outcome enters reconciliation instead of triggering another paid attempt.
We test the behavior, not just the presence of the header. In production certification, an immediate replay of a completed request returned the original request identity without creating another charge. That evidence is more meaningful to me than a unit test that merely proves the code reads Idempotency-Key.
Defects became architecture
Several parts of the architecture came directly from customer-facing failures:
- Provider routing became capability-aware because “another model” was not necessarily compatible.
- Recovery gained durable receipts because a timeout did not prove that no paid job existed.
- Audio became intent-aware because generic narration could technically make a file audible while making the result worse.
- Entitlement checks moved toward an authoritative shared view because stale plan state could break an otherwise correct journey.
- Office and media delivery gained output inspection because generated bytes were not proof of a usable artifact.
- Account deletion gained resumable phases because destructive work must finish completely and safely retry after partial failure.
- Alerts gained provenance because certification tests and capability questions should not be reported as failed customer jobs.
These were not abstract platform goals. They were responses to moments when the product's internal story and the customer's actual experience disagreed.
The public request can stay small
curl https://one.3stoneai.com/v1/chat \
-H "Authorization: Bearer $THREESTONE_API_KEY" \
-H "Idempotency-Key: first-request-001" \
-H "Content-Type: application/json" \
-d '{"model":"3stone-auto","input":"Explain exactly-once API billing simply."}'
The small surface is intentional. Underneath it, the system still needs tenant isolation, request identity, usage attribution, safe retry behavior, and a result the developer can verify.
What I would tell another builder
My biggest shift was moving from provider success to customer-verifiable delivery. If I hope another developer changes one thing after reading this, it is this: do not release the promise represented by an endpoint until you have followed the real output through the customer's next action.
