Quickstart

Three lines. Under five minutes. Any Socaity or APIPod endpoint.

import { socaity, connect } from 'socaity';

socaity.setApiKey('sk_...'); // free key at socaity.ai
const client = await connect('https://api.socaity.ai/services/v1/speechcraft');

const audio = await client.submitJob('/text2voice', { text: 'Welcome to generative AI' });
await audio.save('welcome.mp3');

That is the whole pattern: connect to a service, submit a job, save the result.

Browse the model catalog at socaity.ai/APIs/Overview.

Why socaity-js

Calling AI services from the browser or Node sounds simple until you ship it: long-running jobs need polling, file uploads differ per content type, streaming SSE must be parsed, and every endpoint wants a different request shape.

| | Raw fetch | Generic HTTP client | socaity-js | |---|---|---|---| | Call pattern | Hand-roll every endpoint | One client, no schema awareness | connect() → typed submitJob() | | Long-running jobs | Build your own poll loop | Not included | Built-in job handles + events | | Media I/O | Manual Blob/base64 juggling | Partial | media-toolkit-js in and out | | Streaming | Parse SSE yourself | Varies | job.stream().iterText() / iterBytes() | | Socaity gateway | Wire envelope + links yourself | — | Normalized SocaityJobResponse polling |

Why not use the Python SDK? Use it on the backend. socaity-js is the lightweight JS counterpart: Socaity/APIPod only, no multi-provider layer, pure web APIs (fetch, FormData, streams), ES + UMD builds for browser bundles.

Why not call the REST API directly? You can. This package is the transport layer the Socaity frontend and your apps share — job envelopes, progress events, stream assembly, and media parsing already handled.

Key features

Connect and call. Point at a service URL; the SDK loads its OpenAPI spec and returns a client. Or pass a catalog ServiceDefinition you already have.

Job handles, not blocked HTTP. Every submission returns a Job immediately. Await it, observe progress, stream live, or cancel — in parallel across many calls.

const tts = client.submitJob('/text2voice', { text: 'Hello' });
const img = client.submitJob('/text2img', { prompt: 'A robot at sunset' });
// ... do other work ...
const [audio, images] = await Promise.all([tts, img]);

Streaming built in. Chat tokens, TTS chunks, and binary media streams share one API. Iterate live or let getResult() assemble the full payload.

Files just work. Inputs accept paths (Node), URLs, base64, Blobs/Files (browser), or MediaFile instances. Results with media content arrive as typed ImageFile / AudioFile / VideoFile objects.

Browser-first, Node too. No Node-only HTTP stack — the same bundle runs in Vite/Nuxt and in Node ≥ 20.

Jobs and streaming

Calls return a job handle, not a blocked connection. Poll when ready, cancel when not, run many in parallel.

const job = client.submitJob('/text2img', { prompt: 'A futuristic city at sunset' });

job.onStatus((status) => console.log(status));           // QUEUED → PROCESSING → FINISHED
job.onProgress(({ progress, message }) => console.log(progress, message));

// await job;           // same as job.getResult()
// await job.cancel();  // abort locally + POST links.cancel when present

const images = await job;
await images[0].save('city.jpg');

Live streaming

Schema endpoints (chat, TTS, video) accept stream: true. Iterate tokens or bytes as they arrive:

const job = client.submitJob('/chat', {
  messages: [{ role: 'user', content: 'Explain why an SDK beats raw HTTP.' }],
  stream: true,
});

for await (const text of (await job.stream()).iterText()) {
  process.stdout.write(text); // OpenAI-style SSE deltas
}

Three iterators on StreamSession:

| Method | Returns | |---|---| | iterText() | Joined chat/token text | | iterChunks() | Decoded SSE JSON items | | iterBytes() | Raw network chunks |

If you never call stream(), await job drains the body and assembles the final result (text or typed media file).

Chat and LangChain.js

For chat services there are two purpose-built layers. ChatServiceAdapter speaks the OpenAI wire format (tools, tool_choice, logprobs, reasoning, streaming) without any framework:

import { ChatServiceAdapter } from 'socaity';

const chat = await ChatServiceAdapter.connect(serviceUrl);
const response = await chat.complete({ messages: [{ role: 'user', content: 'hi' }] });

for await (const chunk of chat.streamChunks({ messages })) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

ChatSocaity plugs the same service into LangChain.js (install @langchain/core, it is an optional peer dependency):

import { ChatSocaity } from 'socaity/langchain';

const model = new ChatSocaity({ model: serviceUrl });
const bound = model.bindTools([myTool], { tool_choice: 'auto' });
const answer = await bound.invoke([new HumanMessage('What is the weather in Boston?')]);

Streaming, tool calls, forced tool_choice, reasoning content (additional_kwargs.reasoning_content) and usage metadata all round-trip. The Python SDK ships the same pair (socaity.integrations).

Catalog service definitions

When the Socaity frontend (or your backend) already provides a ServiceDefinition, skip OpenAPI discovery:

import { createClient } from 'socaity';

const client = createClient(serviceDefinition, {
  address: 'https://api.socaity.ai/services/v1/<service_hosting_id>',
});

const result = await client.run('/predict', { text: 'hello' }); // submitJob().getResult() sugar

Resume an in-flight job by ID (gateway convention):

const job = client.trackJob('job-uuid-here', '/predict');
await job;

Authentication

Set your API key globally or per client. Keep secrets out of source control.

import { socaity, connect } from 'socaity';

// Global (typical for apps)
socaity.setApiKey(process.env.SOCAITY_API_KEY!);

// Or per client
const client = await connect(serviceUrl, { apiKey: 'sk_...' });

export SOCAITY_API_KEY=sk_...   # Node / CI

Get a free key at socaity.ai/signinup.

Other global settings: socaity.setBaseUrl(), socaity.setWebBackendUrl(), or socaity.configure({ pollIntervalMs, requestTimeoutMs, jobTimeoutMs }).

Browser and Node.js

| Environment | Import | Notes | |---|---|---| | Browser (ESM) | import { socaity, connect } from 'socaity' | Used by the Socaity frontend via Vite alias in dev | | Browser (UMD) | <script src="socaity.umd.js"> | window.socaity global | | Node ≥ 20 | import { socaity, connect } from 'socaity' | File paths as media inputs; MediaFile.save() to disk |

Local frontend development aliases socaity to the sibling socaity-js/sdk source tree so SDK changes hot-reload instantly. Deployed builds install socaity from npm.

Examples: examples/node_usage/main.js, examples/website_usage/index.html.

The core concepts

| Concept | What it is | |---|---| | Service definition | Normalized description of a service: endpoints, parameters, address. From OpenAPI (connect) or the Socaity catalog (createClient). | | Client | SocaityClient — submits jobs, estimates price, tracks existing jobs. | | Job | User-facing handle: thenable, observable (onStatus, onProgress, …), stream(), cancel(). Mirrors Python's APISeex. | | Schemas | TypeScript interfaces bundled in-package (ServiceDefinition, SocaityJobResponse, AI request types). Mirror Python's socaity-schemas. |

Internal layering (client → job → runtime → streaming) is documented in TECHNICAL_README.md.

Service compatibility

Works out of the box with:

• Socaity.ai hosted services (job queue + gateway)
• APIPod services — plain FastAPI (direct results) and APIPOD_SIMULATE=serverless (polling envelopes)
• Any OpenAPI 3.0 service that follows the same job/stream conventions

Ecosystem

Three packages, one pipeline:

| Package | Role | |---|---| | APIPod | Build and deploy AI services (server side) | | fastSDK | Python client for any compatible API (multi-provider) | | media-toolkit-js | Cross-platform media I/O for JS (this SDK's file layer) | | socaity-js (this repo) | Socaity/APIPod client for browser and Node | | socaity | Python SDK with curated model zoo |

Build a service with APIPod. Consume it with socaity-js in the frontend or Node scripts.

Documentation

| Resource | What you get | |---|---| | socaity.ai | Model catalog, pricing, API keys | | TECHNICAL_README.md | Architecture: job lifecycle, streaming, formatter, tests | | fastSDK README | Python counterpart (broader provider support) | | APIPod README | Build and deploy your own AI services |

Tests

Integration tests mirror fastSDK's APIPod suite. Start the debug test services, then:

npm run build && node test/test_apipod_debug_test_services.mjs

Both launch modes are supported — plain FastAPI and APIPOD_SIMULATE=serverless.

The chat/LangChain suite spawns its own debug services (plain, serverless, serverless-runpod) from the sibling apipod checkout:

npx vitest run test/langchain_chat.test.ts

Status

0.1.0 — active development. Breaking changes from the pre-0.1 API are intentional. Pin your version in production.

Contribute

Issues and pull requests welcome.

git clone https://github.com/SocAIty/socaity-js.git
cd socaity-js
npm install
npm run prod
node test/test_apipod_debug_test_services.mjs

License

MIT. See LICENSE.