Execute AI apps on inference.sh.

Basic Usage

1from inferencesh import inference23client = inference(api_key="inf_your_key")45result = client.run({6    "app": "infsh/flux",7    "input": {"prompt": "A sunset over mountains"}8})910print(f"Task ID: {result['id']}")11print(f"Output: {result['output']}")

Parameters

Parameter	Type	Description
`app`	`string`	App identifier (`namespace/name` or `namespace/name@version`)
`input`	`object`	Input matching app schema
`setup`	`object`	Setup parameters (affects worker warmth)
`infra`	`'cloud' \| 'private'`	Infrastructure type
`variant`	`string`	App variant
`workers`	`string[]`	Specific worker IDs (for private)
`webhook`	`string`	URL to receive a POST when the task completes
`session`	`string`	`'new'` to start a session, or session ID to continue
`session_timeout`	`number`	Session idle timeout in seconds (1-3600, only with `session: 'new'`)

Setup Parameters

Setup parameters configure the app instance. Workers with matching setup are "warm" and start faster:

1result = client.run({2    "app": "infsh/flux",3    "setup": {"model": "schnell"},4    "input": {"prompt": "A sunset"}5})

Private Workers

Run on your own infrastructure:

1result = client.run({2    "app": "my-team/my-app",3    "input": {...},4    "infra": "private",5    "workers": ["worker-id-1"]  # Optional: specific workers6})

Task Status

1from inferencesh import TaskStatus23TaskStatus.QUEUED      # 2 - Waiting4TaskStatus.RUNNING     # 7 - Executing5TaskStatus.CANCELLING  # 8 - Cancelling6TaskStatus.COMPLETED   # 10 - Done7TaskStatus.FAILED      # 11 - Error8TaskStatus.CANCELLED   # 12 - Cancelled

Sessions

Maintain state across multiple calls with sessions. The worker stays warm, preserving loaded models and in-memory state.

1# Start a new session2result = client.run({3    "app": "my-app",4    "input": {"action": "init"},5    "session": "new"6})7session_id = result["session_id"]89# Continue the session10result = client.run({11    "app": "my-app",12    "input": {"action": "process"},13    "session": session_id14})

Custom Session Timeout

Sessions expire after 60 seconds of inactivity by default. Customize with session_timeout (1-3600 seconds):

1# 5-minute idle timeout2result = client.run({3    "app": "my-app",4    "input": {...},5    "session": "new",6    "session_timeout": 3007})

Each successful call resets the idle timer. See Sessions Developer Guide for full documentation.

Webhooks

Get notified when a task completes by providing a webhook URL. When the task reaches a terminal state (completed, failed, or cancelled), a POST request is sent to your URL with the task result.

1result = client.run({2    "app": "my-app",3    "input": {"prompt": "Hello"},4    "webhook": "https://your-server.com/webhook"5}, wait=False)6# Your webhook receives a POST when the task finishes

Webhook Payload

Your endpoint receives a JSON POST with the task result:

json

1{2  "id": "task_abc123",3  "status": 9,4  "output": { "image": { "uri": "https://..." } },5  "error": "",6  "session_id": null,7  "created_at": "2024-01-15T10:30:00Z",8  "updated_at": "2024-01-15T10:30:05Z"9}

Field	Type	Description
`id`	string	Task ID
`status`	number	Terminal status code (9=completed, 10=failed, 11=cancelled)
`output`	object	Task output (when completed)
`error`	string	Error message (when failed)
`session_id`	string	Session ID (if using sessions)
`created_at`	string	ISO timestamp
`updated_at`	string	ISO timestamp

Next Steps

Streaming — Real-time progress updates
Files — File uploads and downloads