DEV Community: Jathan Spaulding

From an AI request to a usable file: jobs, retries, and output validation

Jathan Spaulding — Tue, 06 Oct 2026 17:16:54 +0000

I’m the founder of 3Stone AI. One lesson from building our API was that a successful generation request is only part of the job. The output still has to arrive, open, and be usable.

A provider can return “success” while a customer still has no usable file. The durable product contract is longer:

request → persisted job → provider work → stored artifact → authenticated download → file opens

Below is the production contract we use for an editable Word document. You need a 3Stone API key and funded API balance. Keep the key in an environment variable; never paste it into source control.

1. Submit one artifact request

export THREESTONE_API_KEY="your-key-from-developer-mode"

curl -sS https://one.3stoneai.com/v1/documents \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: onboarding-brief-2026-10-06-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Create a polished two-page onboarding brief for a small software team. Include goals, roles, a first-week checklist, and success criteria."}'

A newly accepted request returns HTTP 202 with a durable job_id and a status such as queued.

{
  "object": "response",
  "capability": "documents",
  "job_id": "<uuid>",
  "status": "queued"
}

The API accepts prompts from 1 to 8,000 characters. The idempotency key must be 8–200 safe characters.

2. Poll the job instead of guessing

JOB_ID="the-job-id-from-step-1"

curl -sS "https://one.3stoneai.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $THREESTONE_API_KEY"

The same account boundary applies to job status and artifact access. A completed response exposes artifact metadata; internal storage paths and provider request IDs are not returned.

A minimal shell loop could look like this:

while true; do
  BODY=$(curl -sS "https://one.3stoneai.com/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer $THREESTONE_API_KEY")
  STATUS=$(printf '%s' "$BODY" | jq -r '.status')
  printf 'status=%s\n' "$STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  [ "$STATUS" = "reconciliation_required" ] && exit 2
  sleep 3
done

3. Download the artifact with the same key

curl -sS "https://one.3stoneai.com/v1/jobs/$JOB_ID/artifact" \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  --output onboarding-brief.docx

Then validate the thing the customer actually receives:

file onboarding-brief.docx
unzip -t onboarding-brief.docx

Those checks confirm the download is an Office package, not an HTML error page saved with a .docx extension. The next layer is product-specific: open it in Word or LibreOffice, inspect headings and lists, edit it, save it, reopen it, and confirm the revision survived.

The lifecycle at a glance

POST /v1/documents + Idempotency-Key
                │
                ▼
      202 + durable job_id
                │
                ▼
       GET /v1/jobs/{id}
   queued → running → completed
                │
                ▼
 GET /v1/jobs/{id}/artifact
                │
                ▼
 open → inspect → edit → save → reopen

Safe retries and billing

Idempotency is part of the billing boundary, not just a convenience.

Reusing the same key with the same request replays the original admission instead of starting unrelated duplicate work.
Reusing that key with a different payload returns HTTP 409 idempotency_conflict.
HTTP 402 means the account needs balance before retrying with a new key.
HTTP 429 enforces the current per-key rate limit of 60 requests per minute.
A reconciliation response is not permission to fire a fresh paid request. Keep the original job and request identifiers and let the uncertain outcome reconcile.

In our implementation, money is reserved before work starts. Completed work settles against measured usage. Failures are either finalized or moved into an explicit reconciliation state when the provider or artifact-storage outcome is uncertain. That distinction matters: blindly generating a new idempotency key can turn uncertainty into a duplicate charge.

Repairs that changed how we verify output

Real customer failures forced us to stop treating a green request as the definition of success. We now separate several states that used to be easy to flatten:

the controller accepted the request;
a worker actually claimed it;
the provider returned;
the artifact was stored;
the authenticated download returned the intended media type;
the file opened and remained editable.

The same lesson applies beyond DOCX. A spreadsheet needs formulas and a workbook that recalculates. A presentation needs editable slide objects, not a screenshot in a PPTX container. A media job needs a playable export with the requested audio behavior.

I’m sharing the contract here because the most useful feedback is concrete: does this job model make integration and recovery clear, and which artifact validation signal would you want returned by the API?

The current developer surface and supported endpoints are at 3stoneai.com/developers.

Why we built one API for AI research, media, and editable artifacts

Jathan Spaulding — Mon, 28 Sep 2026 18:24:39 +0000

A useful AI product often needs more than a text completion. It may need current research with sources, file understanding, generated media, an editable PowerPoint or spreadsheet, durable job state, storage, and usage accounting.

Building each of those paths against a different provider creates a familiar problem: every integration has its own authentication, retry rules, status model, output format, and billing data. The first demo can be quick. The production system is not.

That is the problem we built the 3Stone API to address: one server-side API contract for research, creation, and finished artifacts.

One key, synchronous and asynchronous work

Simple chat can complete synchronously:

const response = await fetch("https://one.3stoneai.com/v1/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THREESTONE_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "3stone-auto",
    input: "Explain the tradeoffs between queues and scheduled polling.",
  }),
});

const result = await response.json();

Creation endpoints use durable jobs. The initial request returns a job ID; clients poll that job and download the artifact only after it reaches a completed state.

const headers = {
  Authorization: `Bearer ${process.env.THREESTONE_API_KEY}`,
  "Content-Type": "application/json",
};

const submitted = await fetch(
  "https://one.3stoneai.com/v1/presentations",
  {
    method: "POST",
    headers: {
      ...headers,
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      prompt: "Create a concise editable project update deck.",
    }),
  },
).then((response) => response.json());

let job;
do {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  job = await fetch(
    `https://one.3stoneai.com/v1/jobs/${submitted.job_id}`,
    { headers },
  ).then((response) => response.json());
} while (["queued", "provider_starting", "running"].includes(job.status));

if (job.status !== "completed") {
  throw new Error(`Job stopped: ${job.error?.code}`);
}

const artifact = await fetch(
  `https://one.3stoneai.com/v1/jobs/${submitted.job_id}/artifact`,
  { headers },
);

The same job pattern applies to spreadsheets, images, and video.

Why idempotency is part of the API contract

Long-running provider work can outlive an HTTP connection. A blind retry can create duplicate provider cost or duplicate customer-visible output. Every mutating request therefore accepts a stable idempotency key.

If the same key is reused with a different body, the API returns an idempotency conflict. If an accepted provider operation cannot yet be authoritatively reconciled, the request can enter a reconciliation-required state. Clients should preserve the request and job IDs instead of replaying the work.

That distinction matters: a network timeout does not prove that external execution failed.

Research should return sources

A research response is only useful when the application can retain and render its evidence:

import json, os, urllib.request, uuid

request = urllib.request.Request(
    "https://one.3stoneai.com/v1/research",
    data=json.dumps({
        "query": "Research current battery recycling policy and cite primary sources."
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['THREESTONE_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request, timeout=120) as response:
    result = json.load(response)
    print(result["output_text"])
    for source in result.get("sources", []):
        print(source["url"])

Finished artifacts, not screenshots

The current public release includes:

AI/chat
source-backed research
file and image understanding
image and video generation
editable PowerPoint, Excel, and document files
music
interactive HTML tools

We deliberately do not advertise public API website/software execution or webhooks yet. Production truth matters more than a long launch list.

Keep the key on the server

Never expose a 3Stone API key in browser or mobile code. Put calls behind your authenticated backend or server function. Persist the returned request and job IDs so reconnecting clients can resume without duplicating work.

Useful production error handling includes:

401 invalid_api_key: reject and rotate/revoke as appropriate.
402 insufficient_balance: fund the usage balance before new provider work.
409 idempotency_conflict: use a new key only when the request body truly changes.
429 rate_limit_exceeded: back off with jitter.
reconciliation_required: preserve identifiers and do not replay blindly.

What we want feedback on

3Stone API is usage-based and separate from consumer subscriptions. Developer Mode exposes keys, balance, request logs, charges, and job state.

I would especially value feedback on:

the durable async-job contract;
artifact lifecycle and download ergonomics;
which end-to-end examples would make evaluation easiest;
which capability combinations are hardest to maintain across separate providers.

Quickstart, OpenAPI, and examples: https://github.com/jathanks3/3stone-developer-apis?utm_source=devto&utm_medium=content&utm_campaign=api_launch

Documentation: https://www.3stoneai.com/developers/docs?utm_source=devto&utm_medium=content&utm_campaign=api_launch

Developer Mode: https://one.3stoneai.com/developer?utm_source=devto&utm_medium=content&utm_campaign=api_launch