Your First Prediction

What you'll be able to do after this module

Make Prediction API calls from cURL, Python, or TypeScript. Understand the full async lifecycle from request to output URL. Read the Prediction Object schema confidently — you already studied it in Module 3.

The prediction lifecycle

Every request to Skytells — image, video, audio — follows the same pattern:

• Fast models (e.g., truefusion-edge): often succeeded in the initial response — no polling needed.
• Standard models (e.g., truefusion-pro): ~5–15 seconds. Poll GET /v1/predictions/:id.
• Video/audio models: 30 seconds to several minutes. Use webhooks (covered in Building Production Apps).

Make your first call

Make sure your API key is in your environment:

export SKYTELLS_API_KEY="sk-your-key-here"

Now send your first prediction:

curl -X POST https://api.skytells.ai/v1/predictions \
  -H "x-api-key: $SKYTELLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "truefusion-pro",
    "input": {
      "prompt": "A photorealistic mountain lake at sunrise, 4K",
      "width": 1024,
      "height": 1024
    }
  }'

Reading the response

A freshly-created prediction looks like this:

{
  "id": "pred_abc123",
  "status": "processing",
  "model": "truefusion-pro",
  "created_at": "2025-01-01T00:00:00Z",
  "output": null
}

When status is processing, poll until succeeded:

curl https://api.skytells.ai/v1/predictions/pred_abc123 \
  -H "x-api-key: $SKYTELLS_API_KEY"

The completed response:

{
  "id": "pred_abc123",
  "status": "succeeded",
  "output": [
    "https://cdn.skytells.ai/outputs/pred_abc123/output.png"
  ],
  "metrics": {
    "predict_time": 8.3,
    "total_time": 9.1
  }
}

Common input parameters

Most image models accept a consistent set of parameters:

Error handling

Always check response.ok (or catch exceptions in SDKs) before trusting the output.

# HTTP errors return a JSON body with a detail field
# Example 401 response:
# { "detail": "Invalid API key" }

# Example 422 response:
# { "detail": "width must be a multiple of 8" }

HTTP status codes

Complete working example

Here's a self-contained script that creates a prediction and downloads the output:

import os
import urllib.request
import skytells

client = skytells.Client(api_key=os.environ["SKYTELLS_API_KEY"])

# 1. Generate
prediction = client.predictions.create(
    model="truefusion-pro",
    input={
        "prompt": "A photorealistic red fox in a snowy forest, golden hour, cinematic",
        "width": 1024,
        "height": 1024,
        "num_inference_steps": 30,
    },
)

assert prediction.status == "succeeded"
image_url = prediction.output[0]
print(f"Generated: {image_url}")

# 2. Download before CDN expiry (24h)
urllib.request.urlretrieve(image_url, "output.png")
print("Saved to output.png")

Summary

Key things to remember:

• Every request uses POST /v1/predictions with model + input
• Predictions have a lifecycle: queued → processing → succeeded/failed
• SDKs poll automatically; with raw HTTP you poll GET /v1/predictions/:id
• Output URLs expire in 24 hours — save them to your own storage
• x-api-key is the required header for the Prediction API

Up next: Module 5 — make your first Inference API call and use Skytells as a drop-in OpenAI-compatible LLM gateway.