Models API

Discover, inspect, and validate AI models — browse the catalog, fetch schemas, and check capabilities before running predictions.

Skytells hosts 30+ AI models spanning image generation, video synthesis, music composition, text generation, code, and multimodal tasks. The Models API lets you discover available models, inspect their input/output schemas, and check capabilities — all before spending a single credit on a prediction.

Access the Models API via client.models. It maps to the Models REST API.

Model metadata is cached in-memory for 10 minutes (64 slugs in default mode, 16 in edge mode). Call client.purgePrefetchedModelCache() to force a refresh.

Listing Models

Retrieve the full list of models available on the platform. Each Model object includes the model's name, type, vendor, pricing, capabilities, and current operational status.

Use this to build model selectors, filter by type, or programmatically discover new models as they're added to the catalog.

List Models

Basic

import Skytells from 'skytells';

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

const models = await client.models.list();

for (const model of models) {
console.log(model.name);          // "TrueFusion"
console.log(model.namespace);     // "truefusion" — slug for API calls
console.log(model.type);          // "image"
console.log(model.vendor.name);   // vendor name
console.log(model.status);        // "operational" or "offline"
console.log(model.capabilities);  // ["text-to-image", "image-to-image"]
console.log(model.pricing);       // { amount: 0.03, currency: "USD", unit: "image" }
}

Getting a Model

Fetch a single model by its slug (the namespace field). This is useful for checking a model exists and is operational before creating a prediction.

The slug is the identifier you pass to client.run(), predictions.create(), and other prediction methods.

Get Model

Basic

const model = await client.models.get('truefusion');

console.log(model.name);            // "TrueFusion"
console.log(model.type);            // "image"
console.log(model.vendor.name);     // vendor info
console.log(model.vendor.verified); // true
console.log(model.pricing);         // { amount, currency, unit }
console.log(model.capabilities);    // ["text-to-image", ...]
console.log(model.metadata);
// { edge_compatible: true, openai_compatible: false, cold_boot: false }

Input & Output Schemas

Request model schemas by passing fields: ['input_schema', 'output_schema']. Schemas follow JSON Schema format and describe exactly what inputs the model accepts and what shape its output takes.

This is especially useful for:

Building dynamic forms from model parameters
Validating user input before calling client.run()
Auto-generating documentation for specific models

Schema fields are not included by default to reduce response size. Pass fields explicitly when you need them.

Schemas

With schemas

const model = await client.models.get('truefusion', {
fields: ['input_schema', 'output_schema'],
});

// Input schema — JSON Schema describing accepted inputs
console.log(model.input_schema);
// {
//   type: "object",
//   properties: {
//     prompt: { type: "string", description: "..." },
//     aspect_ratio: { type: "string", enum: ["1:1", "16:9", ...] },
//     num_outputs: { type: "integer", default: 1, minimum: 1 },
//     ...
//   },
//   required: ["prompt"]
// }

// Output schema
console.log(model.output_schema);

Model Types

Every model has a type field indicating what kind of content it produces. Use the ModelType enum for type-safe filtering:

import type { ModelType } from 'skytells';

// ModelType values:
// 'image' | 'video' | 'audio' | 'music' | 'text' | 'code' | 'multimodal'

Type	Description	Example models
`image`	Image generation & editing	TrueFusion, FLUX Pro, FLUX 2.0
`video`	Video synthesis	Mera
`audio`	Speech & audio processing	—
`music`	Music composition	BeatFusion 2.0
`text`	Text generation & chat	DeepBrain Router
`code`	Code generation	GPT-5.3 Codex
`multimodal`	Multi-input/output	—

Browse the complete list in the Model Catalog.

The Model Object

The Model interface contains everything you need to know about a model before running it.

namestring

Display name (e.g. "TrueFusion").

namespacestring

API slug — pass this to client.run() (e.g. "truefusion").

typeModelType

Content type — see Model Types above.

privacyModelPrivacy

'public' or 'private'. See ModelPrivacy.

vendorVendor

Provider info — name, description, image_url, verified, slug. See Vendor.

pricingPricing

Cost info — amount, currency, unit, optional criterias and formula. See Pricing and Pricing docs.

capabilitiesstring[]

What the model can do (e.g. ["text-to-image", "image-to-image"]).

metadataModelMetadata

Runtime hints — edge_compatible, openai_compatible, cold_boot. See ModelMetadata.

statusstring

"operational" or "offline". Check API Status for platform-wide health.

input_schemaModelInputSchema | null

JSON Schema for inputs — only included when requested via fields. See ModelInputSchema.

output_schemaModelOutputSchema | null

JSON Schema for outputs — only included when requested via fields. See ModelOutputSchema.

// Full Model shape
{
name: "TrueFusion",
namespace: "truefusion",
type: "image",
privacy: "public",
vendor: {
  name: "Skytells AI",
  description: "...",
  image_url: "https://...",
  verified: true,
  slug: "skytells"
},
pricing: {
  amount: 0.03,
  currency: "USD",
  unit: "image"
},
capabilities: ["text-to-image", "image-to-image"],
metadata: {
  edge_compatible: true,
  openai_compatible: false,
  cold_boot: false
},
status: "operational",
billable: true,
// Only when requested with fields:
input_schema: { ... },
output_schema: { ... }
}

Compatibility Check

When you call client.run(), the SDK can optionally prefetch and validate model metadata before sending the prediction request. This catches invalid model slugs early with a clear MODEL_NOT_FOUND error — before you're billed.

const prediction = await client.run('truefusion', {
  input: { prompt: 'A cat' },
}, undefined, {
  compatibilityCheck: true, // validate model slug first
});

The compatibility cache holds metadata for up to 64 models (16 in edge mode) with a 10-minute TTL. Purge it manually if needed:

// Clear cache for a specific model
client.purgePrefetchedModelCache('truefusion');

// Clear entire cache
client.purgePrefetchedModelCache();

Error Handling

import { SkytellsError } from 'skytells';

try {
  const model = await client.models.get('nonexistent-model');
} catch (e) {
  if (e instanceof SkytellsError) {
    switch (e.errorId) {
      case 'MODEL_NOT_FOUND':
        // Model slug doesn't exist — see the catalog
        console.error('Model not found. Browse: /docs/api/v1/models/catalog');
        break;
      case 'UNAUTHORIZED':
        // Invalid API key — see authentication docs
        console.error('Check your API key');
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Too many requests — see reliability docs
        console.error('Rate limited, retry later');
        break;
      default:
        console.error(e.errorId, e.httpStatus, e.message);
    }
  }
}

For the full error reference, see Errors. For retry configuration, see Reliability.

Predictions — Run models and get results
Reference: Model types — Full Model, Vendor, Pricing, ModelMetadata type definitions
Model Catalog — Browse all available models with pricing
Models REST API — Underlying REST endpoints
Pricing — How model pricing works

How is this guide?

List Models

Get Model

Schemas

On this page