Predictions

Create, monitor, and manage image, video, and audio predictions from the terminal with skytells predictions.

Overview

skytells predictions runs inference against any model returned by skytells models ls and manages the resulting jobs — creating, polling, listing, cancelling, and deleting them.

Predictions use the same Skytells API key as the Models commands. See Models & API Keys to configure one with skytells api-key set.

`skytells predictions create`

Generate an image, video, or audio asset using a model namespace.

Syntax

skytells predictions create <model> [--input <json-or-file>] [--prompt <text>] [--webhook <url>] [--wait] [--timeout <seconds>] [--output <directory>] [--json]

Argument	Description
`model`	Model namespace, as returned by `skytells models ls`

Flag	Description
`--input <json-or-file>`	Model-specific JSON object, or `@path/to/input.json` for complex inputs
`--prompt <text>`	Shortcut for an input containing only a `prompt` field
`--webhook <url>`	Webhook URL to notify on prediction lifecycle events
`--wait`	Poll until the prediction reaches a terminal state
`--timeout <seconds>`	Maximum time to wait; defaults to `900`
`--output <directory>`	Wait for completion and download generated assets immediately
`--json`	Output as JSON

Provide exactly one of --input or --prompt. Use skytells models inspect <slug> --schemas to discover a model's accepted input fields.

Prompt shortcut

For models that only require a prompt:

skytells predictions create truefusion \
  --prompt "A portrait of an astronaut in a garden"

The command returns as soon as the API responds, unless --wait or --output is provided.

Model-specific input

Pass model-specific fields as an inline JSON object:

skytells predictions create truefusion \
  --input '{"prompt":"A lighthouse at dusk","aspect_ratio":"16:9","number_of_images":2}' \
  --wait

For complex inputs, load a JSON file with @:

video-input.json

{
  "prompt": "A cinematic flight through a futuristic city",
  "seconds": 8,
  "aspect_ratio": "16:9"
}

skytells predictions create <video-model> \
  --input @video-input.json \
  --wait

Wait and download outputs

Generated output URLs expire five minutes after a prediction completes.

Use --output to wait for a terminal status and download every generated file into a directory immediately:

skytells predictions create truefusion \
  --prompt "A botanical illustration of an orchid" \
  --output ./generated

The default timeout is 900 seconds — increase it for longer video models:

skytells predictions create <video-model> \
  --input @video-input.json \
  --output ./generated \
  --timeout 1800

Webhooks

skytells predictions create truefusion \
  --prompt "A studio product photograph" \
  --webhook https://example.com/webhooks/skytells

`skytells predictions get`

Retrieve the latest status and outputs for a single prediction.

skytells predictions get <id> [--json]

`skytells predictions ls`

List recent predictions, optionally filtered by model, status, or date range.

Syntax

skytells predictions ls [--model <slug>] [--status <status>] [--from <date>] [--to <date>] [--page <n>] [--per-page <n>] [--json]

Flag	Description
`--model <slug>`	Filter by model namespace
`--status <status>`	Filter by status: `succeeded`, `failed`, `processing`, `queued`, `cancelled`
`--from <date>`	Start date, `YYYY-MM-DD`
`--to <date>`	End date, `YYYY-MM-DD`
`--page <n>`	Page number
`--per-page <n>`	Results per page, `1`-`50`

Examples

skytells predictions ls
skytells predictions ls --model truefusion --status succeeded
skytells predictions ls --from 2026-08-01 --to 2026-08-13
skytells predictions ls --page 2 --per-page 50 --json

`skytells predictions cancel`

Cancel a queued or processing prediction. Only predictions in those states can be cancelled.

skytells predictions cancel <id> [--json]

Cancelled predictions cannot be resumed.

`skytells predictions rm`

Permanently delete a prediction and its associated output.

skytells predictions rm <id> [-f, --force] [--json]

This action cannot be undone.

CI example

export SKYTELLS_API_KEY="$CI_SKYTELLS_API_KEY"

skytells predictions create truefusion \
  --input @prediction-input.json \
  --output ./artifacts \
  --json > prediction.json

Use SKYTELLS_AI_API_URL only when targeting a compatible non-production API endpoint. Its default is https://api.skytells.ai/v1.

Models & API Keys — discover models and configure your API key.
Console: Predictions — view every prediction across API, SDK, CLI, and Playground sources.
API: Predictions — the underlying REST API.
Skytells MCP — create and manage predictions from an MCP-compatible client.

How is this guide?

On this page