Programmatic access for developers.
Everything in the workspace is available via API. Run apps, execute flows, and (soon) interact with agents from your own code.
Quick Start
Get an API Key
- Go to Settings → API Keys
- Click Create API Key
- Copy your key (starts with
inf_)
Install an SDK
Python:
bash
1pip install inferenceshJavaScript/TypeScript:
bash
1npm install @inferencesh/sdkRun Your First App
Python:
python
1from inferencesh import inference2 3client = inference(api_key="inf_your_key")4 5result = client.run({6 "app": "infsh/echo",7 "input": {"message": "Hello from the API!"}8})9 10print(result["output"])JavaScript:
typescript
1import { inference } from '@inferencesh/sdk';2 3const client = inference({ apiKey: 'inf_your_key' });4 5const result = await client.run({6 app: 'infsh/echo',7 input: { message: 'Hello from the API!' }8});9 10console.log(result.output);Running Apps
Basic Usage
python
1result = client.run({2 "app": "username/app-name", # App identifier3 "input": { # Input matching schema4 "prompt": "A sunset",5 "style": "photorealistic"6 }7})With Setup Parameters
Setup parameters configure the app instance (e.g., model selection). They affect worker warmth and scheduling—workers with matching setup parameters skip the setup phase:
python
1result = client.run({2 "app": "username/flux",3 "setup": {"model": "schnell"}, # Setup parameters4 "input": {"prompt": "A sunset"}5})Fire and Forget
Get the task ID immediately without waiting:
python
1task = client.run({2 "app": "username/slow-app",3 "input": {...}4}, wait=False)5 6print(f"Task started: {task['id']}")Stream Progress
Watch the task in real-time:
python
1for update in client.run(params, stream=True):2 print(f"Status: {update['status']}")3 if update.get('logs'):4 print(update['logs'])Running Flows
Deployed flows work exactly like apps:
python
1result = client.run({2 "app": "username/image-enhancement-flow",3 "input": {"image": "/path/to/image.png"}4})The flow executes all its steps and returns the final output.
File Handling
Automatic Upload
Local file paths are uploaded automatically:
python
1result = client.run({2 "app": "image-processor",3 "input": {4 "image": "/path/to/local/image.png" # Uploaded for you5 }6})Manual Upload
python
1file = client.upload_file("/path/to/file.png")2print(f"Uploaded: {file['uri']}")3 4result = client.run({5 "app": "image-processor",6 "input": {"image": file["uri"]}7})Downloading Results
Output files come as URIs:
python
1result = client.run(params)2output_url = result["output"]["image"]["uri"]3 4# Download it5import requests6response = requests.get(output_url)7with open("output.png", "wb") as f:8 f.write(response.content)Private Execution
Run on your own infrastructure:
python
1result = client.run({2 "app": "username/app",3 "input": {...},4 "infra": "private" # Use your private workers5})Or specify exact workers:
python
1result = client.run({2 "app": "username/app",3 "input": {...},4 "infra": "private",5 "workers": ["worker-id-1", "worker-id-2"]6})Agent SDK
Build headless AI agents with tools and multi-turn conversations:
Python:
python
1from inferencesh import Agent, tool, string2 3calculator = (4 tool("calculator")5 .describe("Do math")6 .param("expression", string("Math expression"))7 .build()8)9 10agent = Agent(11 api_key="inf_...",12 config={13 "core_app_ref": "infsh/claude-sonnet-4@latest",14 "system_prompt": "You help with math.",15 "tools": [calculator],16 }17)18 19response = agent.send_message("What is 42 * 17?")JavaScript:
typescript
1import { inference, tool, string } from '@inferencesh/sdk';2 3const calculator = tool('calculator')4 .describe('Do math')5 .param('expression', string('Math expression'))6 .build();7 8const client = inference({ apiKey: 'inf_...' });9const agent = client.agent({10 core_app_ref: 'infsh/claude-sonnet-4@latest',11 system_prompt: 'You help with math.',12 tools: [calculator],13});14 15const response = await agent.sendMessage('What is 42 * 17?');REST API
Use any language with the REST API:
Run an App
bash
1curl -X POST https://api.inference.sh/apps/run \2 -H "Authorization: Bearer inf_your_key" \3 -H "Content-Type: application/json" \4 -d '{5 "app": "infsh/echo",6 "input": {"message": "Hello!"}7 }'With setup parameters:
bash
1curl -X POST https://api.inference.sh/apps/run \2 -H "Authorization: Bearer inf_your_key" \3 -H "Content-Type: application/json" \4 -d '{5 "app": "infsh/flux",6 "setup": {"model": "schnell"},7 "input": {"prompt": "A sunset"}8 }'Get Task Status
bash
1curl https://api.inference.sh/tasks/task_id \2 -H "Authorization: Bearer inf_your_key"Stream Updates
bash
1curl -N https://api.inference.sh/tasks/task_id/stream \2 -H "Authorization: Bearer inf_your_key" \3 -H "Accept: text/event-stream"Task Status Codes
| Status | Code | Meaning |
|---|---|---|
| Received | 1 | Task received |
| Queued | 2 | Waiting for worker |
| Scheduled | 3 | Assigned to worker |
| Preparing | 4 | Setting up environment |
| Serving | 5 | Loading model |
| Setting Up | 6 | Task initialization |
| Running | 7 | Executing |
| Uploading | 8 | Uploading results |
| Completed | 9 | Done! |
| Failed | 10 | Error occurred |
| Cancelled | 11 | Cancelled by user |
Error Handling
python
1try:2 result = client.run(params)3except RuntimeError as e:4 print(f"Task failed: {e}")Common errors:
"Invalid API key"— Check your key"App not found"— Check the app identifier"Input validation failed"— Check input schema"Task failed"— App error (check logs)
Rate Limits
| Endpoint | Limit |
|---|---|
| Run task | 100/minute |
| Get task | 1000/minute |
| Upload file | 50/minute |
Headers show your status:
code
1X-RateLimit-Remaining: 952X-RateLimit-Reset: 1640000000What's Next?
- Python SDK — Full Python SDK reference
- JavaScript SDK — Full JS/TS SDK reference
- Tool Builder — Define tools for agents
- Extending Apps — Build apps to use via API