Running Apps

Execute AI apps on inference shell.

Basic Usage

1from inferencesh import inference23client = inference(api_key="inf_your_key")45result = client.tasks.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

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 with infra: 'private', or prefer private workers with automatic cloud fallback using infra: 'private_first':

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.

Task Management

After starting a task without waiting, use the client.tasks namespace to check on it, cancel it, or attach to its stream:

1from inferencesh import inference, TaskStatus23client = inference(api_key="inf_your_key")45task = client.tasks.run({"app": "infsh/flux", "input": {...}}, wait=False)67# Poll or wait (optional timeout in seconds)8state = client.tasks.get(task["id"])9result = client.tasks.wait_for_completion(task["id"], timeout=300)1011# Cancel12client.tasks.cancel(task["id"])1314# Stream an in-flight task15with client.tasks.stream(task["id"]) as stream:16    for update in stream:17        if update["status"] == TaskStatus.COMPLETED:18            print(update["output"])19            break

The Python async client exposes the same methods: await client.tasks.get(...), await client.tasks.wait_for_completion(..., timeout=...), async with client.tasks.stream(...), and await client.tasks.cancel(...).

wait_for_completion streams task updates and GET-reconciles if the stream ends without a terminal event. See Streaming — stream completion and GET reconciliation. JavaScript has no wait_for_completion; pass wait: true (the default) to client.run, or drive the stream yourself with StreamManager.

client.cancel(id), client.getTask(id) and client.streamTask(id) are shorthands for the three client.tasks calls above.

Deleting tasks and their files

A finished task can be deleted, with or without the files it consumed and produced. You can also list or delete the files and keep the task.

1# List the task's files: each has id, uri and role ("input" or "output")2files = client.tasks.files(task_id).data34# Delete the files, keep the task5result = client.tasks.delete_files(task_id).data6print(result["deleted"], result["skipped"])78# Delete only the outputs9client.tasks.delete_files(task_id, role="output")1011# Delete the task; files=True deletes its files too12client.tasks.delete(task_id, files=True)

These calls need a finished task; a queued or running one answers 409. Files are deleted even when another task, flow or chat still uses them, so pass role="output" if you reuse an uploaded input. Without files, deleting a task leaves its files in your workspace. See Tasks API for the response fields.

Concurrent Tasks

Each call is an independent request, so run them with the concurrency primitive of the language:

1import asyncio2from inferencesh import async_inference34async def main():5    client = async_inference(api_key="inf_your_key")67    results = await asyncio.gather(*[8        client.tasks.run({"app": "infsh/flux", "input": {"prompt": p}})9        for p in prompts10    ])

Concurrent tasks count against your plan's concurrency limit. Every task is still accepted; at the cap the scheduler either dispatches anyway or holds the task Queued until a slot frees, depending on the plan's enforcement. See Concurrent task limits.

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:

1{2  "event": "task.completed",3  "timestamp": "2024-01-15T10:30:05Z",4  "data": {5    "id": "task_abc123",6    "short_id": "abc123",7    "status": 10,8    "status_text": "completed",9    "output": { "image": { "uri": "https://..." } },10    "created_at": "2024-01-15T10:30:00Z",11    "updated_at": "2024-01-15T10:30:05Z"12  }13}

data fields:

The webhook is sent when the task reaches a terminal status. Delivery is not retried: a failed request or a 4xx/5xx response is logged and dropped. The request times out after 10 seconds, and only public addresses are called.

Next Steps

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