Making API Requests

Authentication

All requests to the Skytells API must be authenticated. The only supported method is API Key authentication — pass your key in the x-api-key header with every request.

If you don't have an API key yet, see Generating an API Key.

Making Authenticated Requests

Include the x-api-key header in every API call. The interactive examples below show the exact request format for each endpoint.

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Response Body

`application/json`

curl -X GET "https://api.skytells.ai/v1/models"

[
  {
    "name": "TrueFusion",
    "description": "TrueFusion Standard",
    "namespace": "truefusion",
    "type": "image",
    "status": "operational",
    "capabilities": [
      "text-to-image",
      "image-to-image"
    ],
    "pricing": {
      "amount": 0.03,
      "currency": "USD",
      "unit": "image"
    },
    "vendor": {
      "name": "Skytells",
      "verified": true,
      "slug": "skytells"
    },
    "input_schema": {},
    "output_schema": {}
  }
]

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

The model namespace to run.

input*

Input parameters for the model. Varies by model.

webhook?string

Optional webhook URL to receive prediction events.

Response Body

`application/json`

curl -X POST "https://api.skytells.ai/v1/predictions" \  -H "Content-Type: application/json" \  -d '{    "model": "truefusion",    "input": {      "prompt": "A photo of a cat in a spaceship"    }  }'

{
  "id": "pred_abc123",
  "status": "succeeded",
  "model": "truefusion",
  "input": {},
  "output": "https://cdn.skytells.ai/outputs/pred_abc123.png",
  "created_at": "2026-03-07T12:00:00Z",
  "started_at": "2026-03-07T12:00:01Z",
  "completed_at": "2026-03-07T12:00:05Z",
  "metrics": {
    "predict_time": 4.2
  },
  "error": "string"
}

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Response Body

`application/json`

curl -X GET "https://api.skytells.ai/v1/predictions/pred_abc123"

{
  "id": "pred_abc123",
  "status": "succeeded",
  "model": "truefusion",
  "input": {},
  "output": "https://cdn.skytells.ai/outputs/pred_abc123.png",
  "created_at": "2026-03-07T12:00:00Z",
  "started_at": "2026-03-07T12:00:01Z",
  "completed_at": "2026-03-07T12:00:05Z",
  "metrics": {
    "predict_time": 4.2
  },
  "error": "string"
}

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

Inference API & Schemas

For text and embedding workloads, use the Inference API. It is OpenAI-compatible and uses the same API key authentication (x-api-key) described above.

Core inference endpoints:

POST /chat/completions
POST /responses
POST /embeddings

Example: Chat Completions Request

curl https://api.skytells.ai/v1/chat/completions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepbrain-router",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Summarize our privacy policy in 3 bullet points."}
    ]
  }'

Interactive Inference Endpoints

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Query Parameters

stream?boolean

Force streaming via query param. Equivalent to stream: true in the body.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

The model namespace. Use deepbrain-router for automatic routing.

Value in"deepbrain-router" | "gpt-5" | "gpt-5.4"

messages*array<>

Conversation history as an array of message objects.

stream?boolean

If true, responses are streamed as server-sent events.

Defaultfalse

max_tokens?integer

Maximum number of tokens to generate.

Default8192

temperature?number

Sampling temperature (0–2). Lower = more deterministic.

Default0.7

Range0 <= value <= 2

top_p?number

Nucleus sampling probability (0–1).

Default0.95

Range0 <= value <= 1

frequency_penalty?number

Penalise tokens based on their frequency in the output (-2.0–2.0).

Default0

Range-2 <= value <= 2

presence_penalty?number

Penalise tokens that have appeared at all (-2.0–2.0).

Default0

Range-2 <= value <= 2

stop?|array<>

Stop sequences. Generation halts when any sequence is encountered.

Response Body

`application/json`

curl -X POST "https://api.skytells.ai/v1/chat/completions" \  -H "Content-Type: application/json" \  -d '{    "model": "deepbrain-router",    "messages": [      {        "role": "system",        "content": "You are a helpful assistant."      },      {        "role": "user",        "content": "Hello!"      }    ]  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1748000000,
  "model": "deepbrain-router",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 38,
    "total_tokens": 62
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Value in"deepbrain-router" | "gpt-5" | "gpt-5.4"

input*|array<>

The input for the response. A string or array of message objects.

previous_response_id?string

ID of a prior response to continue the conversation.

stream?boolean

Defaultfalse

max_output_tokens?integer

Default8192

temperature?number

Default0.7

Range0 <= value <= 2

top_p?number

Default0.95

instructions?string

System-level instructions prepended to the conversation.

Response Body

`application/json`

curl -X POST "https://api.skytells.ai/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "deepbrain-router",    "input": "What is machine learning?"  }'

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1748000000,
  "model": "deepbrain-router",
  "status": "completed",
  "output_text": "Machine learning is a subset of AI...",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Machine learning is a subset of AI..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 41,
    "total_tokens": 53
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

Authorization

apiKey

x-api-key<token>

Your Skytells API key. Obtain one from Dashboard → API Keys.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Value in"deepbrain-router" | "gpt-5" | "gpt-5.4"

input*|array<>

Text to embed. String or array of strings for batch embedding.

encoding_format?string

Format of the returned embedding vectors.

Default"float"

Value in"float" | "base64"

dimensions?integer

Number of dimensions in the output vector.

Response Body

`application/json`

curl -X POST "https://api.skytells.ai/v1/embeddings" \  -H "Content-Type: application/json" \  -d '{    "model": "deepbrain-router",    "input": "The quick brown fox jumps over the lazy dog."  }'

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797101
      ]
    }
  ],
  "model": "deepbrain-router",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

{
  "error": {
    "message": "The model 'unknown-model' was not found.",
    "type": "server_error",
    "code": "model_not_found",
    "error_id": "MODEL_NOT_FOUND",
    "status": 404,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

Using an SDK

If you use one of the official SDKs, authentication is handled automatically — just pass your API key when creating the client:

import { createClient } from 'skytells';

const client = createClient(process.env.SKYTELLS_API_KEY);

The SDK attaches the correct headers to every request for you.

When a request fails authentication, the API returns 401 using the unified error envelope (status, response, nested error). Branch on error.error_id (stable codes are uppercase):

{
    "status": false,
    "response": "Invalid API key",
    "error": {
        "http_status": 401,
        "message": "Invalid or missing API key, Please obtain a valid API key from the Skytells Console",
        "details": "Invalid API key",
        "error_id": "UNAUTHORIZED"
    }
}

ACCOUNT_SUSPENDED also uses 401. A negative account balance is 402 with PAYMENT_REQUIRED — see API errors — 401 / 402.

Common auth-related error_id values:

`error_id`	Meaning
`UNAUTHORIZED`	API key missing, invalid, or revoked.
`ACCOUNT_SUSPENDED`	Account cannot make API calls.

The same unified envelope applies across auth, models, predictions, and other REST routes — always read error.error_id.

Enforced Rate Limits

Skytells applies scoped limits (per account, route, model, and tier). For Inference and Edge, usage appears in x-skytells-ratelimit-* headers on successful responses; 429 responses may include Retry-After. On REST routes (including Predictions), 429 uses the same unified envelope with error.error_id such as RATE_LIMIT_EXCEEDED — see Prediction errors and Rate limits.

See Rate limits for accurate header names, Retry-After rules, and handling RATE_LIMITED vs RATE_LIMIT_EXCEEDED.

For full API authentication details, see the Skytells Authentication Docs.

How is this guide?

200application/json

401application/json

201application/json

401application/json

422application/json

200application/json

401application/json

404application/json

200

400application/json

401application/json

402application/json

404application/json

422application/json

429application/json

500application/json

503application/json

504application/json

200application/json

400application/json

401application/json

402application/json

429application/json

500application/json

200application/json

400application/json

401application/json

402application/json

429application/json

500application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`