The official inference.sh SDKs for Python and JavaScript/TypeScript.

Both SDKs send X-API-Version: 2 on every request, so responses use bare JSON objects and RFC 9457 errors. Raw curl calls without that header get the legacy wrapped format — see REST API versioning.

Installation

1# Installation2pip install inferencesh34# With async support5pip install inferencesh[async]

Quick Start

1from inferencesh import inference23client = inference(api_key="inf_your_key")45# Run an app and wait for result6result = client.tasks.run({7    "app": "infsh/flux",8    "input": {"prompt": "A sunset over mountains"}9})1011print(result["output"])

Client structure

Both SDKs expose namespaced APIs on the client. The JavaScript SDK covers the full REST surface; Python currently ships the core run/chat namespaces.

Namespace	Purpose	Python	JavaScript
`tasks`	Run, get, cancel, list, and stream app tasks	✓	✓
`files`	Upload, list, get, and delete files	✓	✓
`agents`	Create agents and send messages	✓	✓
`sessions`	List, inspect, keepalive, and end sessions	✓	✓
`apps`	List, create, and manage deployed apps	—	✓
`chats`	List and manage chats; `getTrace()` for agent observability	—	✓
`engines`	List, drain, update, and extend cloud engine rentals	—	✓
`flows` / `flowRuns`	Flow definitions and run lifecycle (`flowRuns.create`, `stream`, `streamTasks`)	—	✓
`search`	Programmatic `/suggest` and `/search`	—	✓
`knowledge` / `skills`	Knowledge and skill CRUD	—	✓
`teams`, `secrets`, `apiKeys`, `integrations`, `projects`, `mcpServers`	Workspace and connector management	—	✓

Top-level run() / uploadFile() (JavaScript) and run() / upload_file() (Python) are legacy aliases for tasks.run() and files.upload().

When a namespace is JavaScript-only, call the equivalent REST endpoint from Python until the SDK adds helpers.

Inspect and observability (JavaScript)

Method	REST endpoint	Description
`client.tasks.getLogs(id)`	`GET /tasks/{id}/logs`	Structured task log lines
`client.tasks.getTimings(id)`	`GET /tasks/{id}/timings`	Phase durations from status events
`client.tasks.getTelemetry(id)`	`GET /tasks/{id}/telemetry`	Time-series CPU, RAM, GPU, and volume samples
`client.chats.getTrace(id)`	`GET /chats/{id}/trace`	Agent execution graph (nodes, edges, step counts)

→ Tasks REST API · Agents REST API · Observability

Both SDKs call the API with X-API-Version: 2 (bare DTOs, RFC 9457 errors). Use inferencesh ≥ v0.7.8 or @inferencesh/sdk ≥ v0.6.11 for the full JavaScript REST surface (knowledge, teams, search, task observability helpers, and related namespaces).

→ Python SDK · JavaScript SDK · REST API versioning

What's in the SDK?

Running Apps

Execute AI apps on inference.sh infrastructure.

Running Apps — Basic task execution
Streaming — Real-time progress updates
Files — File uploads and downloads

Agent SDK

Build and interact with AI agents programmatically.

Agent SDK Overview — Introduction
Template Agents — Use existing agents
Ad-hoc Agents — Create agents on-the-fly
Building Tools — Define custom tools (client, app, HTTP/call, webhook, MCP)

Server Proxy

Protect API keys in frontend applications.

Server Proxy — Proxy setup for all frameworks
Vercel Deployment — Deploy with Vercel integration

Building Apps

Create your own apps to run on inference.sh. → See Extend overview or Extending Apps for the app development guide.

Environment Variables

1import os2from inferencesh import inference34client = inference(api_key=os.environ["INFERENCE_API_KEY"])

TypeScript Support

The JavaScript SDK includes full TypeScript definitions:

typescript

1import type { Task, ApiTaskRequest, InferenceConfig } from '@inferencesh/sdk';

Browser & Node.js

The JavaScript SDK works in both environments:

typescript

1// Node.js (CommonJS)2const { inference } = require('@inferencesh/sdk');34// ES Modules / TypeScript5import { inference } from '@inferencesh/sdk';67// Browser (ESM CDN)8import { inference } from 'https://esm.sh/@inferencesh/sdk';

Note: Never expose API keys in client-side code. Use the Server Proxy in production.

Requirements

Python 3.8+
requests for sync client
aiohttp for async client (optional)

Node.js 18.0.0+
Modern browsers with fetch support

Language references

JavaScript SDK — Full TypeScript/JavaScript API
Python SDK — Full Python API