Edge API

Route latency-sensitive calls through the Skytells Edge gateway for ultra-low latency AI responses. Available for Business and Enterprise accounts on supported models only.

What is the Edge API?

Skytells operates two API gateways:

Gateway	Base URL	Purpose
Standard	`https://api.skytells.ai/v1`	All accounts — all models
Edge	`https://edge.skytells.ai/v1`	Business & Enterprise — Edge-supported models only

The Edge gateway is physically distributed across multiple regions. Requests are routed to the nearest point of presence, reducing network round-trip time significantly.

Edge availability: The Edge API requires a Business or Enterprise account. It is not available on Free or Pro plans, and it only works with models that explicitly support Edge routing.

Edge-supported models

Not all models are available through the Edge gateway. Only the following models support Edge routing:

Model	Type	Avg latency on Edge
`truefusion-edge`	Image	< 1.5s
`flux-1-edge`	Image	< 2s
Chat completion endpoints	Text	< 100ms time-to-first-token

All other models — truefusion-pro, truefusion-ultra, truefusion-video-pro, veo-3.1, sora-2, beatfusion-2.0, etc. — do not support Edge routing and must use the Standard API (api.skytells.ai).

Sending a non-Edge model to edge.skytells.ai will return a 422 error with the message: "This model does not support Edge routing."

When to use Edge

Use case	Use Edge?
Interactive real-time image preview (user is watching)	Yes — use `truefusion-edge`
Live product image generation	Yes — use `truefusion-edge` or `flux-1-edge`
Chatbot / streaming text responses	Yes — chat endpoints
Background batch image generation	No — use Standard API
Video generation (any model)	No — Standard only
Audio generation (BeatFusion)	No — Standard only
High-quality final renders	No — use `truefusion-pro` on Standard

Switching to Edge

Only the base URL changes. Everything else — model IDs, input parameters, API keys — stays identical.

// Standard API — all accounts, all models
const BASE = 'https://api.skytells.ai/v1';

// Edge API — Business/Enterprise, Edge-supported models only
const BASE = 'https://edge.skytells.ai/v1';

Make it configurable via environment variable:

// lib/skytells.ts
const BASE_URL =
  process.env.SKYTELLS_USE_EDGE === 'true'
    ? 'https://edge.skytells.ai/v1'
    : 'https://api.skytells.ai/v1';

export async function createPrediction(model: string, input: object) {
  const res = await fetch(`${BASE_URL}/predictions`, {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SKYTELLS_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model, input }),
  });
  return res.json();
}

Real-time preview with `truefusion-edge`

A typical real-time preview pattern — generate a low-resolution preview on Edge, then queue a high-quality final render on Standard:

// app/api/preview/route.ts  (Business/Enterprise — Edge)
export async function POST(req: Request) {
  const { prompt } = await req.json();

  const res = await fetch('https://edge.skytells.ai/v1/predictions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SKYTELLS_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'truefusion-edge',
      input: { prompt, width: 512, height: 512, num_inference_steps: 4 },
    }),
  });

  const prediction = await res.json();
  return Response.json({ output: prediction.output }); // typically already succeeded
}

// app/api/render/route.ts  (all accounts — Standard API)
export async function POST(req: Request) {
  const { prompt } = await req.json();

  const res = await fetch('https://api.skytells.ai/v1/predictions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SKYTELLS_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'truefusion-pro',  // Not Edge-supported — use Standard
      input: { prompt, width: 1024, height: 1024, num_inference_steps: 30 },
      webhook: 'https://yourapp.com/api/webhooks/render',
    }),
  });

  return Response.json(await res.json());
}

Routing strategy

Use both gateways together for the best user experience:

export async function handleGenerate(prompt: string) {
  // Fire both in parallel
  const [preview, final] = await Promise.allSettled([
    // Edge: instant preview (Business/Enterprise only, Edge model)
    fetch('https://edge.skytells.ai/v1/predictions', {
      method: 'POST',
      headers: { 'x-api-key': process.env.SKYTELLS_API_KEY!, 'Content-Type': 'application/json' },
      body: JSON.stringify({ model: 'truefusion-edge', input: { prompt, width: 512, height: 512, num_inference_steps: 4 } }),
    }).then(r => r.json()),

    // Standard: high-quality final (any account, async)
    fetch('https://api.skytells.ai/v1/predictions', {
      method: 'POST',
      headers: { 'x-api-key': process.env.SKYTELLS_API_KEY!, 'Content-Type': 'application/json' },
      body: JSON.stringify({ model: 'truefusion-pro', input: { prompt, width: 1024, height: 1024 }, webhook: '/api/webhooks/render' }),
    }).then(r => r.json()),
  ]);

  return {
    previewUrl: preview.status === 'fulfilled' ? preview.value.output?.[0] : null,
    finalPredictionId: final.status === 'fulfilled' ? final.value.id : null,
  };
}

Edge rate limits

Edge rate limits follow the same spend-based tier system as the Standard API, with more conservative ceilings to protect shared infrastructure.

Tier	Monthly Spend	Edge RPM	Concurrent Streams
Business (Tier 3)	$500–$2,000	75	10
Business (Tier 4)	$2,000+	Higher	Higher
Enterprise	Per contract	Custom	Custom

Measuring improvement

Always benchmark to confirm the latency gain in your deployment region:

async function measureLatency(endpoint: 'standard' | 'edge') {
  const base =
    endpoint === 'edge'
      ? 'https://edge.skytells.ai/v1'
      : 'https://api.skytells.ai/v1';

  const times: number[] = [];
  for (let i = 0; i < 5; i++) {
    const start = performance.now();
    await fetch(`${base}/predictions`, {
      method: 'POST',
      headers: { 'x-api-key': process.env.SKYTELLS_API_KEY!, 'Content-Type': 'application/json' },
      body: JSON.stringify({ model: 'truefusion-edge', input: { prompt: 'test', width: 512, height: 512, num_inference_steps: 4 } }),
    }).then(r => r.json());
    times.push(performance.now() - start);
  }

  const avg = times.reduce((a, b) => a + b) / times.length;
  console.log(`${endpoint}: avg ${Math.round(avg)}ms over 5 requests`);
}

Summary

You've completed the Building Production Apps path:

Auth & key management — x-api-key header, separate keys per environment
Webhooks — signature verification, idempotency, async processing
Rate limits & errors — exponential backoff, queuing, budget guardrails
Edge API — ultra-low latency for Business/Enterprise on Edge-supported models

Next steps:

SDK Mastery — cleaner production code with official SDKs
Enterprise & Compliance — security, privacy, governance
API Reference — complete technical reference

PreviousRate Limits & Error Handling