Prediction Overview

Predictions

Predictions are the core of the Skytells API. Every model request — whether generating an image, a video, or running any AI service creates a prediction. A prediction represents a single execution of a model with specific input parameters. It tracks the entire lifecycle of that execution, from creation to completion, including status, output, and metadata.

Predictions can be created, retrieved, listed, canceled, and deleted via all of our interfaces such as REST API, SDKs, and Playground Console. Each prediction has a unique ID and a rich set of fields describing its status, input, output, timing metrics, billing info, and more.

Create Prediction

POST /v1/predictions — Run a model with specified input parameters.

Get Prediction

GET /v1/predictions/{id} — Retrieve details and status of a prediction.

List Predictions

GET /v1/predictions — List your recent predictions.

Cancel Prediction

POST /v1/predictions/{id}/cancel — Cancel an in-progress prediction.

Delete Prediction

DELETE /v1/predictions/{id} — Permanently delete a prediction.

Prediction Lifecycle

Status	Description
`queued`	The prediction is waiting to be processed.
`processing`	The model is actively running.
`succeeded`	The prediction completed successfully. Output is available.
`failed`	The prediction encountered an error. See the `error` field.
`canceled`	The prediction was canceled before completion.

Prediction Schema

Every prediction shares the same top-level structure regardless of model type. The input, output, and parts of metrics vary depending on the model you use.

Each model type requires a different request body when creating a prediction. Refer to the model-specific documentation for exact input parameters, or use the interactive API playground below.

Try Create Prediction

Open the POST /v1/predictions API playground to create a prediction with your own parameters.

The Prediction Object

Prediction Object

Image

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "succeeded",
  "stream": false,
  "type": "inference",
  "input": {
    "prompt": "A portrait of an astronaut in a garden"
  },
  "output": [
    "https://delivery.skytells.cloud/us/2026/03/04/a1b2c3d4-output.png"
  ],
  "created_at": "2026-03-04T21:20:58.000000Z",
  "started_at": "2026-03-04T21:20:58+00:00",
  "completed_at": "2026-03-04T21:21:09+00:00",
  "updated_at": "2026-03-04T21:21:09.000000Z",
  "privacy": "private",
  "source": "api",
  "model": {
    "name": "FLUX.2-pro",
    "type": "image"
  },
  "webhook": {
    "url": "https://your-server.com/webhook",
    "events": ["prediction.succeeded", "prediction.failed"]
  },
  "metrics": {
    "image_count": 1,
    "predict_time": 10.899,
    "total_time": 10.899,
    "asset_count": 1
  },
  "metadata": {
    "billing": {
      "credits_used": 0.02
    },
    "storage": {
      "files": []
    },
    "data_available": true
  },
  "urls": {
    "get": "https://api.skytells.ai/v1/predictions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cancel": "https://api.skytells.ai/v1/predictions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel",
    "stream": "https://api.skytells.ai/v1/predictions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stream",
    "delete": "https://api.skytells.ai/v1/predictions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/delete"
  }
}

Top-Level Fields

Field	Type	Description
`id`	`string`	Unique UUID identifying this prediction.
`status`	`string`	Current lifecycle status. One of: `queued`, `processing`, `succeeded`, `failed`, `canceled`.
`stream`	`boolean`	`true` if the prediction was created in streaming mode; `false` otherwise.
`type`	`string`	Always `"inference"` for model predictions.
`input`	`object`	Model-specific input parameters. Schema varies per model — see input object.
`output`	`string[] \| null`	Array of output URLs on success; `null` while queued, processing, or on failure.
`created_at`	`string`	ISO 8601 timestamp when the prediction was created.
`started_at`	`string`	ISO 8601 timestamp when inference began. May equal `created_at` for fast-start models.
`completed_at`	`string`	ISO 8601 timestamp when inference finished.
`updated_at`	`string`	ISO 8601 timestamp of the last status change.
`privacy`	`string`	Visibility of the prediction: `"private"` or `"public"`.
`source`	`string`	Origin of the request: `"api"` (created via API key) or `"web"` (created from the dashboard).
`model`	`object`	Model identifier. See model object.
`webhook`	`object`	Webhook configuration for this prediction. See webhook object.
`metrics`	`object`	Timing and count metrics. See metrics object.
`metadata`	`object`	Billing and storage info. See metadata object.
`urls`	`object`	Pre-built action URLs for this prediction. See urls object.
`error`	`string \| null`	Present and non-null only when `status` is `"failed"`. Contains the inference error message.

model object

OBJECT The model object identifies which model processed the prediction.

model

Image

{
  "name": "FLUX.2-pro",
  "type": "image"
}

Field	Type	Description
`name`	`string`	The model's namespace slug (e.g. `"FLUX.2-pro"`, `"beatfusion-2.0"`, `"truefusion-x"`).
`type`	`string`	Model category: `"image"`, `"audio"`, or `"video"`.

webhook object

OBJECTThe webhook object reflects the configuration you supply when creating a prediction via POST /v1/predictions. If you include a webhook URL and events array in your create request, they appear here. Both fields are empty/null when no webhook was registered.

webhook

With webhook

{
  "url": "https://your-server.com/webhook",
  "events": ["prediction.succeeded", "prediction.failed"]
}

Field	Type	Description
`url`	`string \| null`	The endpoint that receives POST notifications, or `null` if not set.
`events`	`string[]`	Subscribed event types. Empty array `[]` if no webhook was registered. Possible values: `"prediction.succeeded"`, `"prediction.failed"`, `"prediction.canceled"`.

metrics object

Timing fields (predict_time, total_time) are always present. Additional fields depend on the model type.

metrics

Image

{
  "image_count": 1,
  "predict_time": 10.899,
  "total_time": 10.899,
  "asset_count": 1
}

Field	Type	Models	Description
`predict_time`	`number`	All	Seconds spent on model inference, excluding queue wait time.
`total_time`	`number`	All	Total wall-clock seconds from creation to completion, including queue and setup.
`image_count`	`number`	Image only	Number of images generated in this prediction.
`asset_count`	`number`	Image, Video	Total number of output assets produced.
`progress`	`number`	Video only	Completion percentage (0–100) reported by the model during generation.

metadata object

OBJECT The metadata object contains billing consumption and output file storage details.

metadata

With files

{
  "billing": {
    "credits_used": 0.75
  },
  "storage": {
    "files": [
      {
        "name": "output.mp3",
        "type": "audio/mpeg",
        "size": 2124868,
        "url": "https://delivery.skytells.cloud/us/2026/03/06/b2c3d4e5-output.mp3"
      }
    ]
  },
  "data_available": true
}

Field	Type	Description
`billing.credits_used`	`number`	Credits deducted for this prediction. Amount varies by model and output complexity.
`storage.files`	`object[]`	Stored output files while `data_available` is `true`. Each entry contains `name` (filename), `type` (MIME type), `size` (bytes), and `url` (download URL). Returns an empty array `[]` once the retention window expires or if storage was skipped.
`data_available`	`boolean`	`true` while outputs are accessible. Becomes `false` once the 5-minute retention window has passed and outputs are purged from Skytells storage.

When data_available is false, all output URLs are permanently inaccessible. Download and persist your outputs immediately upon receiving the prediction.succeeded webhook. Skytells does not retain prediction outputs beyond 5 minutes after completion.

urls object

OBJECT The urls object provides pre-built endpoints for every action on this specific prediction. Use these instead of constructing URLs manually.

urls

{
  "get": "https://api.skytells.ai/v1/predictions/{id}",
  "cancel": "https://api.skytells.ai/v1/predictions/{id}/cancel",
  "stream": "https://api.skytells.ai/v1/predictions/{id}/stream",
  "delete": "https://api.skytells.ai/v1/predictions/{id}/delete"
}

Field	HTTP Method	Description
`get`	`GET`	Retrieve the latest state of this prediction, including output when complete.
`cancel`	`POST`	Cancel the prediction. Only valid when `status` is `"queued"` or `"processing"`.
`stream`	`GET`	Open a Server-Sent Events (SSE) stream for real-time incremental output. Only available when `stream: true` was set at creation time.
`delete`	`DELETE`	Permanently delete this prediction and its associated outputs. Irreversible.

input object

The input schema is model-specific. Each model type expects different parameters — always check the model's documentation or fetch the schema dynamically.

input

Image (text-to-image)

{
  "prompt": "A portrait of an astronaut in a garden"
}

The full input schema for each model — including all accepted parameters, types, and defaults — is available at GET /v1/models/{slug}. The response includes an input_schema field with a complete JSON Schema definition.

output object

OBJECT The output field is always an array of CDN URLs pointing to the generated files. All outputs are delivered through the Skytells CDN. It is null while the prediction is queued, processing, failed, or canceled.

output

Image

[
  "https://delivery.skytells.cloud/us/2026/03/04/a1b2c3d4-output.png"
]

Model type	Output format	Notes
`image`	`.png`, `.jpg`, `.webp`	Multiple images possible when the model supports batch generation.
`audio`	`.mp3`	Full audio file for the completed generation.
`video`	`.mp4`	Single video file. Duration determined by `input.seconds`.

Please Note: All outputs are delivered through the Skytells CDN. It is null while the prediction is queued, processing, failed, or canceled, Please Consider to save the output URLs and download your assets immediately upon receiving the prediction.succeeded webhook notification. Skytells does not retain output data more than 5 minutes after a prediction is completed.

Learn more about output retention and best practices in the Data Retention and Data Governance sections.

How is this guide?

Create Prediction

Get Prediction

List Predictions

Cancel Prediction

Delete Prediction

Try Create Prediction

Prediction Object

model

webhook

metrics

metadata

urls

input

output

On this page