TypeScript SDK Guide

The official JavaScript/TypeScript SDK for interacting with the Skytells API. Works in Node.js, browsers, and edge runtimes.

View on GitHub npm Package

At Skytells, we believe the best developer experience starts with a single, unified SDK. The TypeScript SDK is your gateway to the entire Skytells platform — from running predictions on 30+ AI models to building automated Orchestrator workflows, all through one consistent interface.

Whether you're generating images with TrueFusion, streaming chat completions with DeepBrain, browsing the model catalog, or embedding text for semantic search, the SDK handles authentication, polling, retries, and type safety so you can focus on building.

This SDK ships ESM and CJS builds with full TypeScript declarations included. Zero dependencies — optimized for edge environments.

Installation

Adding to your project

The Skytells TypeScript SDK is distributed as an npm package and can be installed with your preferred package manager. It has zero dependencies and is optimized for edge environments.

After installation, you can import the SDK into your project and start making API calls with just a few lines of code.

Jump to Quick Start

Install

npm

npm install skytells

Package.json Setup

{
  "dependencies": {
    "skytells": "^1.0.5"
  }
}

Quick Start

Getting Started with Skytells

The SDK provides a simple and intuitive interface for the Skytells API. The main entry point is the default Skytells export, which returns a client instance with methods for running predictions, chat completions, embeddings, and more.

The example on the right demonstrates the basic workflow:

Import and initialize the client with your API key
Run a prediction using a model
Process the results

All API methods return promises. The SDK requires an API key — it does not read environment variables automatically.

Predictions REST API Browse Model Catalog

Basic Usage

Creating a client

import Skytells from 'skytells';

// Initialize the client with your API key
const skytells = Skytells('your-api-key');

Complete Example

import Skytells from 'skytells';

async function main() {
  const skytells = Skytells('your-api-key');

  // List available models
  const models = await skytells.models.list();
  console.log('Available models:', models.map(m => m.name));

  // Generate a video using Mera model
  const prediction = await skytells.run('mera', {
    input: { prompt: 'A video of a cat playing with a ball', seconds: '8', size: '720x1280' },
  });

  console.log('Status:', prediction.status);    // "starting", "running", "succeeded", "failed"
  console.log('Output:', prediction.outputs()); // "https://..."
  // Generating a video takes time, so we can wait for the prediction to complete
}

main().catch(console.error);

Framework Integration

Using with Popular Frameworks

The Skytells SDK integrates seamlessly with all popular JavaScript and TypeScript frameworks. Below are examples for the most common frameworks.

The key consideration when integrating is API key security — keep your keys on the server side and never expose them to clients.

Server Components, Edge functions, and API routes are ideal places to use the Skytells SDK as they keep your API key secure. See Security for more.

Framework Examples

Next.js App Router

// app/docs/api/generate/route.ts
import Skytells from 'skytells';
import { NextResponse } from 'next/server';

// Disable Next.js fetch cache with custom fetch
const skytells = Skytells(process.env.SKYTELLS_API_KEY, {
  fetch: (url, opts) => fetch(url, { ...opts, cache: 'no-store' }),
});

export async function POST(request: Request) {
  const { prompt } = await request.json();

  const prediction = await skytells.run('MODEL_NAME', {
    input: { prompt },
  });

  return NextResponse.json({
    output: prediction.outputs(),
    id: prediction.id,
  });
}

UI Integration Example (React)

// TextGenerationForm.tsx — calls your API route
import { useState } from 'react';

export default function GenerateForm() {
const [prompt, setPrompt] = useState('');
const [output, setOutput] = useState('');
const [loading, setLoading] = useState(false);

const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault();
  setLoading(true);
  try {
    const res = await fetch('/docs/api/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt }),
    });
    const data = await res.json();
    setOutput(data.output);
  } catch {
    setOutput('Error generating content.');
  } finally {
    setLoading(false);
  }
};

return (
  <form onSubmit={handleSubmit}>
    <textarea value={prompt} onChange={(e) => setPrompt(e.target.value)} />
    <button type="submit" disabled={loading}>
      {loading ? 'Generating...' : 'Generate'}
    </button>
    {output && <div>{output}</div>}
  </form>
);
}

Edge Compatibility

The Skytells TypeScript SDK works in any environment with Fetch API support. No special configuration needed.

Cloudflare Workers / Pages
Vercel Edge Functions
Netlify Edge Functions
Deno Deploy
Node.js 18+
Browsers — use a backend proxy for API key security

Edge Runtimes

Cloudflare Worker

import Skytells from 'skytells';

export default {
async fetch(request, env) {
  const skytells = Skytells(env.SKYTELLS_API_KEY);

  const prediction = await skytells.run('flux-pro', {
    input: { prompt: 'A sunset over mountains' },
  });

  return new Response(JSON.stringify(prediction.output), {
    headers: { 'Content-Type': 'application/json' },
  });
},
};

Authentication

Setting Up Authentication

To access the Skytells API, you need an API key from your Skytells dashboard. API keys start with sk- and authenticate your requests.

The SDK supports both authenticated and unauthenticated clients, though most functionality requires authentication.

Never expose your API key in client-side code. For browser applications, use a backend service to proxy your API requests.

Get your API key

Learn more about authentication

Authentication Options

Basic Auth

import Skytells from 'skytells';

// With API key (authenticated)
const skytells = Skytells('sk-your-api-key');

Environment Variables

In a Node.js environment, you can use environment variables to store your API key securely:

// .env file
SKYTELLS_API_KEY=sk-your-api-key

// In your code
import Skytells from 'skytells';

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

How is this guide?