Build with the capabilities that are live today.

Quickstart

1. Sign in to 3Stone and open Developer Mode.
2. Add at least $10 to the separate prepaid API balance.
3. Create and immediately save a named API key. The secret is shown once.
4. Export it as THREESTONE_API_KEY and send a unique Idempotency-Key with every POST request.

curl

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 billing simply.","max_output_tokens":256}'

JavaScript / TypeScript

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 exactly-once billing simply.",
    max_output_tokens: 256,
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error?.message ?? `HTTP ${response.status}`);
console.log(result.output_text);

Python

import json, os, uuid, urllib.request, urllib.error

request = urllib.request.Request(
    "https://one.3stoneai.com/v1/chat",
    data=json.dumps({
        "model": "3stone-auto",
        "input": "Explain exactly-once billing simply.",
        "max_output_tokens": 256,
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['THREESTONE_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        print(json.load(response)["output_text"])
except urllib.error.HTTPError as error:
    raise SystemExit(json.load(error)["error"]["message"]) from error

3Stone Chat models

If model is omitted, Chat defaults to 3stone-auto. Auto classifies the task and selects a certified path using complexity, context, quality, latency and provider availability. It is not a hard-coded alias for the least expensive model.

These stable 3Stone names protect integrations from routine upstream model changes. Raw provider model identifiers are not accepted. Responses include the requested public model, measured usage, request ID and charge; internal provider routing is not part of the public contract.

Authentication and key safety

Send the secret as Authorization: Bearer 3stone_sk_…. Keep it in a server-side environment variable. Never ship it in browser or mobile client code, a public repository, logs, screenshots, or support messages. Keys are stored as hashes, can be revoked immediately and do not grant consumer-session, Project, Owner or Admin access.

Create separate named keys for separate server environments. Rotate by creating a replacement, updating the server secret, verifying it, and revoking the old key. The API intentionally does not support credentialed cross-origin browser calls: use it from your server.

Billing

API funds and consumer plans are independent. A paid consumer plan is not required. Stripe confirms payment before the append-only 3Stone ledger credits the balance. A request reserves its maximum bounded charge before work begins, then settles measured usage with sub-cent precision and releases the unused reservation.

Every successful response or completed job includes usage.charge_cents and usage.charge_microusd. Synchronous responses also include the resulting balance_cents. Developer Mode shows the authoritative request log and ledger-backed balance.

You can set a daily spending limit. Optional auto-reload uses the threshold and reload amount you choose; disabling it stops new automatic funding attempts. Funding and auto-reload operations are protected against duplicate ledger credits.

Production endpoints

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 billing simply.","max_output_tokens":256}'

curl https://one.3stoneai.com/v1/research \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: research-request-001" \
  -H "Content-Type: application/json" \
  -d '{"input":"Research this topic and cite authoritative sources.","max_output_tokens":1200}'

curl https://one.3stoneai.com/v1/files/analyze \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: file-request-001" \
  -H "Content-Type: application/json" \
  -d '{"input":"Describe the useful details.","files":[{"media_type":"image/png","data":"BASE64_IMAGE_DATA"}]}'

curl https://one.3stoneai.com/v1/images \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: image-request-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A realistic solar-powered neighborhood library at golden hour"}'

curl https://one.3stoneai.com/v1/presentations \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: presentation-request-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Create a five-slide editable launch plan for a neighborhood bakery."}'

curl https://one.3stoneai.com/v1/music \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: music-request-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Warm instrumental R&B with electric piano and soft drums","duration_seconds":8,"instrumental":true}'

curl https://one.3stoneai.com/v1/video \
  -H "Authorization: Bearer $THREESTONE_API_KEY" \
  -H "Idempotency-Key: video-request-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Subtle natural motion, locked camera, no text","input_image":"BASE64_JPEG_OR_PNG","media_type":"image/jpeg","ratio":"1280:720"}'

Errors and retries

Errors use {"error":{"code","message","request_id"}}. A 400 invalid_model rejects anything outside the documented public 3Stone aliases. A 401 rejects an invalid or revoked key; 402 means insufficient balance; 409 protects an existing idempotency identity; 429 enforces rate limits; and a reconciliation-related 503 must not be retried under a new key.

Retry the identical request with the identical idempotency key. Reusing a key for a changed payload returns 409 without starting work or charging again.

Jobs and artifacts

Creation endpoints return HTTP 202 with a durable job_id. Poll GET /v1/jobs/{id} with the same ordinary API key until the job is completed, failed or requires reconciliation. A completed job includes a key-protected artifact URL at GET /v1/jobs/{id}/artifact.

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

Keep the original idempotency key. An identical retry recovers the same request and job; a changed payload returns 409. Never start replacement work while a job requires reconciliation.

Usage, limits and capability status

One account, one key and one prepaid balance cover every certified capability. Each API key is limited to 60 requests per minute across endpoints. Developer Mode supports a daily spending limit; reservations that would exceed the balance or limit fail before provider execution.

Validate file type and size before encoding, do not submit secrets in prompts, and treat generated output as untrusted until your application validates it. API request and artifact handling is described in the Privacy Policy.

All sections describe capabilities of 3Stone API, not separate provider products. Provider routing remains behind the stable 3Stone contract. An unavailable capability is never advertised as live.