Predictions

Predictions are the core functionality of the Skytells API — they allow you to generate content using various AI models. With our powerful prediction endpoints, you can create images, text, videos, or combinations of content types simply by providing a prompt and model-specific parameters. This documentation covers everything you need to know to implement prediction capabilities in your applications.

Authenticating Predictions

All prediction endpoints require authentication using an API key. Include your API key in the x-api-key header with all requests:

x-api-key: your-api-key-here

You can obtain your API key from the Skytells Dashboard.

Navigation

Supported Models - View all available AI models and their capabilities
Credit Management - Learn about credit system and pricing
Webhooks - Set up webhooks for prediction status updates
Rate Limits - Understand API usage limits and best practices

Prediction Schema

The prediction model contains all the information about your predictions, including their status, input parameters, output results, and associated metadata.

Properties

Property	Type	Description
`id`	string	Unique identifier for the prediction (UUID).
`status`	string	Current status of the prediction: starting, processing, succeeded, failed, or canceled.
`stream`	boolean	Whether streaming is enabled for this prediction.
`type`	string	The type of prediction, typically "inference" for standard AI model predictions.
`input`	object	The input parameters used for the prediction. Important: This varies significantly by model type. Each model has its own specific input schema and required parameters.
`output`	array	Array of output URLs generated by the prediction.
`created_at`	timestamp	Timestamp of when the prediction was created.
`started_at`	timestamp	Timestamp of when the prediction started processing.
`completed_at`	timestamp	Timestamp of when the prediction completed.
`updated_at`	timestamp	Timestamp of when the prediction was last updated.
`privacy`	string	Privacy setting for the prediction, can be "private" or "public".
`source`	string	Source of the prediction request, typically "api" or "dashboard".
`model`	object	Information about the model used for prediction, including its name and type (e.g., "image", "text", "video").
`webhook`	object	Webhook configuration for receiving updates.
`metrics`	object	Performance metrics for the prediction, including processing time and resource usage.
`metadata`	object	Additional metadata including billing, storage information, and data availability status.
`urls`	object	URLs for accessing and managing the prediction, including get, cancel, stream, and delete endpoints.

Prediction Input Schema

When creating a prediction, the input parameter is highly dependent on the specific model you're using. Each model type has its own set of required and optional parameters designed for its specific capabilities.

How Model Inputs Work

Model Type Determines Input Schema: Different model types (image, text, video, audio) have fundamentally different input requirements.
Parameter Validation: The API validates input parameters based on the model's requirements. Invalid parameters will result in a validation error.
Default Values: Many parameters have default values that will be used if not explicitly provided.
Model Versions: Different versions of the same model may have slightly different parameter requirements.

Finding Model-specific Documentation

To find the appropriate parameters for a specific model:

Navigate to the Supported Models page
Select your model of interest
Review the "Input Parameters" section for that model
Note required vs. optional parameters

Testing and Optimizing Parameters

When working with a new model, we recommend:

Start with a simple test using only required parameters
Gradually add optional parameters to refine results
Experiment with parameter values to find the optimal settings for your use case
Keep track of parameters used for successful predictions for future reference

Advanced parameters often have the most significant impact on output quality. Don't hesitate to experiment with values like guidance, steps, and temperature to achieve your desired results.

Input Schema by Model Type

Model-specific Input Examples

{
  "prompt": "A futuristic cityscape with flying cars",
  "negative_prompt": "blurry, low quality, distorted",
  "steps": 30,
  "guidance": 7.5,
  "width": 768,
  "height": 768,
  "num_outputs": 1,
  "seed": 12345,
  "safety_checker": true
}

POST/v1/predict

Create a prediction

Every cloud model request whatever the model type is, creates a prediction. Prediction is a core object that contains all the information about your predictions, including their status, input parameters, output results, and associated metadata.

This endpoint allows you to create a new prediction using a specified model. The prediction will be processed asynchronously unless the await parameter is set to true. However, When you specify a webhook url and event, Skytells will notify your server for every prediction event.

Required attributes

Name
model
Type
string
Description
The model name to use for prediction (e.g., "truefusion", "deepbrain").
Name
input
Type
object
Description
Model-specific input parameters.

Optional attributes

Name
await
Type
boolean
Description
Whether to wait for the prediction to complete before returning a response.
Name
webhook
Type
object
Description
Webhook configuration for receiving updates about prediction status changes.
- Name
  url
  Type
  string
  Description
  URL to receive webhook notifications.
- Name
  events
  Type
  array
  Description
  Array of events to trigger webhooks (e.g., "succeeded", "failed", "processing").

Common input parameters

Name
prompt
Type
string
Description
The text prompt describing what to generate.
Name
negative_prompt
Type
string
Description
Text describing what to avoid in the generation.
Name
steps
Type
integer
Description
Number of inference steps (default varies by model, typically 20-50).
Name
guidance
Type
float
Description
Guidance scale controlling how closely the model follows the prompt (typically 5.0-15.0).
Name
seed
Type
integer
Description
Random seed for reproducible results. Use the same seed to generate similar outputs.
Name
width
Type
integer
Description
Width of the generated image in pixels (model-specific constraints apply).
Name
height
Type
integer
Description
Height of the generated image in pixels (model-specific constraints apply).
Name
num_outputs
Type
integer
Description
Number of outputs to generate (default: 1, max depends on model).
Name
output_format
Type
string
Description
Format of the output (e.g., "jpg", "png", "mp4").
Name
output_quality
Type
integer
Description
Quality of the output image (1-100, default: 90).
Name
safety_checker
Type
boolean
Description
Whether to apply safety filtering to avoid generating harmful content.

The parameters above are primarily for image generation models. Text, video, and audio models will have completely different input parameters. Always refer to the specific model documentation for the correct input schema.

Request

POST

/v1/predict

curl -X POST "https://api.skytells.ai/v1/predict" \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "truefusion",
    "safety_checker": true,
    "stream": false,
    "gpu": "H100",
    "input": {
      "prompt": "A man sitting on a computer",
      "aspect_ratio": "1:1"
    },
    "webhook": {
      "url": "https://example.com/webhook",
      "events": ["succeeded", "failed"]
    }
  }'

Response

{
  "success": true,
  "message": "Prediction succeeded",
  "data": {
    "id": "some-prediction-id",
    "status": "succeeded",
    "stream": false,
    "type": "inference",
    "input": {
      "prompt": "A man sitting on a computer chair in a high-tech office, digital art style",
      "negative_prompt": "blurry, low quality, distorted, unrealistic",
      "steps": 30,
      "guidance": 7.5,
      "width": 768,
      "height": 768,
      "num_outputs": 1,
      "safety_checker": true
    },
    "output": [
      "OUTPUT_URL_1",
      "OUTPUT_URL_2",
      "OUTPUT_URL_3"
    ],
    "created_at": "2025-03-20T23:11:24.000000Z",
    "started_at": "2025-03-20T23:10:58.777197281Z",
    "completed_at": "2025-03-20T23:11:23.714830014Z",
    "updated_at": "2025-03-20T23:11:24.000000Z",
    "privacy": "private",
    "source": "api",
    "model": {
      "name": "truefusion",
      "type": "image"
    },
    "webhook": {
      "url": "https://example.com/webhook",
      "events": ["succeeded", "failed"]
    },
    "metrics": {
      "image_count": 1,
      "predict_time": 24.937632732
    },
    "metadata": {
      "billing": {
        "credits_used": 0.01
      },
      "storage": {
        "files": [
          {
            "name": "some-file-name.jpg",
            "type": "image/jpeg",
            "size": 287418,
            "url": "OUTPUT_URL_1"
          }
        ]
      },
      "data_available": false
    },
    "urls": {
      "get": "https://api.skytells.ai/v1/predictions/some-prediction-id",
      "cancel": "https://api.skytells.ai/v1/predictions/some-prediction-id/cancel",
      "stream": "https://api.skytells.ai/v1/predictions/some-prediction-id/stream",
      "delete": "https://api.skytells.ai/v1/predictions/some-prediction-id/delete"
    }
  }
}

The input parameters vary depending on the model. Each model type (image, text, video, audio) requires different parameters. Check the Supported Models page for specific model requirements and constraints.

GET/v1/predictions/:id

Get a prediction

This endpoint allows you to retrieve the status and results of a specific prediction by providing its ID. You can only access predictions that you own.

The prediction status will be one of: starting, processing, succeeded, failed, or canceled.

Path parameters

Name
id
Type
string
Description
The unique identifier (UUID) of the prediction to retrieve.
Name
stream
Type
boolean
Description
Whether to stream the prediction results.
Name
output
Type
string
Description
The output of the prediction, it can be an array of urls or a string.
Name
input
Type
object
Description
The input used to create the prediction.
Name
created_at
Type
string
Description
The timestamp when the prediction was created.
Name
started_at
Type
string
Description
The timestamp when the prediction started processing.
Name
status
Type
enum
Description
The status of the prediction, It can be one of the following: starting, processing, succeeded, failed, canceled.
Name
type
Type
string
Description
The type of the prediction.

Response

The response includes all information about the prediction, including its current status, input parameters, output URLs (if completed), and associated metadata.

For predictions with status succeeded, the output array will contain URLs to the generated content. For predictions with status failed, check the error information in the response.

Please note that Skytells does not store the outputs more than 15 minutes from the prediction completion.

We're highly recommend you to store the outputs on your own server as soon as possible for the sake of your business, you may check if the data still available by checking the data_available field.

Request

GET

/v1/predictions/{id}

curl -X GET "https://api.skytells.ai/v1/predictions/{id}" \
  -H "x-api-key: your-api-key-here"

Response

{
  "id": "SOME-PREDICTION-ID",
  "status": "succeeded",
  "stream": false,
  "type": "inference",
  "input": {
    "prompt": "A man sitting on a computer chair in a high-tech office, digital art style",
    "negative_prompt": "blurry, low quality, distorted, unrealistic",
    "steps": 30,
    "guidance": 7.5,
    "width": 768,
    "height": 768,
    "num_outputs": 1,
    "safety_checker": true
  },
  "output": [
    "OUTPUT_URL_1",
    "OUTPUT_URL_2",
    "OUTPUT_URL_3"
  ],
  "created_at": "2025-03-20T23:11:24.000000Z",
  "started_at": "2025-03-20T23:10:58.777197281Z",
  "completed_at": "2025-03-20T23:11:23.714830014Z",
  "updated_at": "2025-03-20T23:11:24.000000Z",
  "privacy": "private",
  "source": "api",
  "model": {
    "name": "truefusion-pro",
    "type": "image"
  },
  "webhook": {
    "url": "https://example.com/webhook",
    "events": ["succeeded", "failed"]
  },
  "metrics": {
    "image_count": 1,
    "predict_time": 24.937632732
  },
  "metadata": {
    "billing": {
      "credits_used": 0.01
    },
    "storage": {
      "files": [
        {
          "name": "file-name.jpg",
          "type": "image/jpeg",
          "size": 287418,
          "url": "OUTPUT_URL_1"
        }
      ]
    },
    "data_available": false
  },
  "urls": {
    "get": "https://api.skytells.ai/v1/predictions/SOME-PREDICTION-ID",
    "cancel": "https://api.skytells.ai/v1/predictions/SOME-PREDICTION-ID/cancel",
    "stream": "https://api.skytells.ai/v1/predictions/SOME-PREDICTION-ID/stream",
    "delete": "https://api.skytells.ai/v1/predictions/SOME-PREDICTION-ID/delete"
  }
}