Skytells Python SDK

Run AI models with a single function call.

Official Python SDK for the Skytells AI platform. Run image, video, audio, music, text, and code models with a single function call.

Zero dependencies — uses Python's stdlib urllib for HTTP.

pip install skytells

Quick Start

First, you'll need to get an API key from the Skytells Dashboard.

Then, you can use the SDK to run a model and get the output.

from skytells import SkytellsClient

client = SkytellsClient("sk-your-api-key")

# Run a model and get output
prediction = client.run("truefusion", input={"prompt": "An astronaut riding a rainbow unicorn"})
print(prediction.output)  # "https://..."

# Clean up when done
prediction.delete()

Generating a song using Beatfusion:

prediction = client.run("beatfusion-2.0", input={
    "prompt": "Rap, hip-hop",
    "lyrics": "Let me introduce the voice you hear, Beatfusion by Skytells making it clear.."
})
print(prediction.output)

Browse the full model catalog at skytells.ai/explore/models.

Skytells is committed to the responsible and ethical use of AI. All models are subject to our usage policies and comply with applicable laws and regulations. Learn more at learn.skytells.ai.

Installation

pip install skytells

Requires Python 3.8+. No external dependencies.

Usage

Client Configuration

from skytells import SkytellsClient

client = SkytellsClient(
    "sk-your-api-key",
    base_url="https://api.skytells.ai/v1",   # optional override
    timeout=30000,                             # ms (default: 60000)
    headers={"X-Custom-Header": "value"},      # extra headers
    retry={"retries": 3, "retry_delay": 1000}, # retry config
)

Run a Model

prediction = client.run("truefusion", input={"prompt": "A sunset over mountains"})
print(prediction.output)   # str or list[str]
print(prediction.id)
print(prediction.status)

Progress Tracking

def on_progress(p):
    print(f"Status: {p['status']}, Progress: {p.get('metrics', {}).get('progress', 'n/a')}")

prediction = client.run(
    "truefusion",
    input={"prompt": "A cat"},
    on_progress=on_progress,
)

Background Predictions

# Create without waiting
response = client.predictions.create({
    "model": "truefusion-ultra",
    "input": {"prompt": "A dog"},
})
print(response["id"], response["status"])  # "pending"

# Wait for completion
result = client.wait(response)
print(result["output"])

# Or poll manually
result = client.predictions.get(response["id"])

Queue & Dispatch

client.queue({"model": "truefusion-ultra", "input": {"prompt": "Cat"}})
client.queue({"model": "flux-pro", "input": {"prompt": "Dog"}})
client.queue({"model": "flux-edge", "input": {"prompt": "Bird"}})

results = client.dispatch()
for pred in results:
    print(pred["id"], pred["status"])

Prediction Lifecycle

# Cancel a running prediction
client.cancel_prediction("pred_abc123")

# Delete a prediction and its assets
client.delete_prediction("pred_abc123")

# Stream endpoint
stream_info = client.stream_prediction("pred_abc123")
print(stream_info["urls"]["stream"])

Models API

# List all models
models = client.models.list()
for model in models:
    print(model["name"], model["type"])

# With schemas
models = client.models.list(fields=["input_schema"])

# Fetch a single model
model = client.models.get("flux-pro")
print(model["name"], model["pricing"])

model = client.models.get("flux-pro", fields=["input_schema", "output_schema"])
print(model["input_schema"])

Predictions API

# List predictions with filters
result = client.predictions.list(model="flux-pro", since="2026-01-01", page=2)
for pred in result["data"]:
    print(pred["id"], pred["status"])

print(result["pagination"])

The Prediction Object

client.run() returns a Prediction instance:

outputs() behaviour

Async Client

import asyncio
from skytells import AsyncSkytellsClient

async def main():
    client = AsyncSkytellsClient("sk-your-api-key")
    prediction = await client.run("flux-pro", input={"prompt": "A cat"})
    print(prediction.output)
    await prediction.delete()

asyncio.run(main())

Error Handling

from skytells import SkytellsError

try:
    prediction = client.run("flux-pro", input={"prompt": "test"})
except SkytellsError as e:
    print(e.error_id)    # e.g. "UNAUTHORIZED", "MODEL_NOT_FOUND"
    print(e.http_status) # e.g. 401, 404
    print(e.details)     # human-readable detail string
    print(str(e))        # error message

Error IDs

For a full reference of API-level and prediction-level errors, see the Skytells Error Reference.

Client Options

Type Reference

All types are importable from skytells.types:

from skytells.types import (
    PredictionStatus,
    PredictionType,
    PredictionSource,
    ModelType,
    ModelPrivacy,
    PricingUnit,
    ApiErrorId,
)

License

MIT — see LICENSE.