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

Developing a versatile AI application often requires more than just text generation. Such systems may need to handle current research with sources, file comprehension, generated media, editable presentations or spreadsheets, persistent job state, data storage, and usage tracking. Engineering each of these capabilities to work with separate providers introduces a common challenge: each integration comes with its own authentication methods, retry policies, status indicators, output structures, and billing details.

The initial prototype can be developed swiftly. However, the final robust system proves to be more complex. This is the issue that the 3Stone API was designed to solve: a unified server-side API contract for research, content creation, and finalized artifacts. One master key governs both synchronous and asynchronous operations. Simple chat interactions can be handled synchronously. Here is an example of how to complete a request:

```javascript

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();

```

For content creation, durable jobs are utilized. The initial request returns a job identifier; clients monitor this job until it reaches a completed state before downloading the artifact. The headers and request body remain consistent across calls. The process involves periodically checking the job status until it transitions to "completed".

If the job is not yet finished, an error is thrown. The final artifact can be retrieved from the job details. This same approach applies to generating spreadsheets, images, and videos. Idempotency is a crucial aspect of the API contract. Long-running provider tasks might outlive an HTTP session. A retry without considering idempotency could lead to duplicate charges or duplicate outputs that customers can see.

Therefore, every request that changes data must include a stable idempotency key. If the same key is used with different data, the API returns an error indicating an idempotency conflict. If an operation's outcome cannot be verified, the request may move into a reconciliation-required state. Clients should store the request and job identifiers rather than retrying the operation.

This separation is important because a network timeout does not necessarily mean that the external execution failed. Retrieving research information necessitates retaining sources. The API provides a research endpoint that returns cited sources along with the information requested. Here is an example of how to fetch research data:

```javascript

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",

},

);

```

By providing a single API contract, 3Stone simplifies the integration process for developers building diverse AI applications. This unified approach reduces the complexity typically associated with managing multiple provider-specific APIs, enabling faster development and more reliable deployment of sophisticated, multi-functional AI systems.