Integration Guide

Connect your app to NXS API in minutes. Use the fal SDK on the server with requestMiddleware, or call the REST API directly.

Get your API key →

server.ts

import { fal } from "@fal-ai/client";

fal.config({
  credentials: "nxs_your_key",
  requestMiddleware: async (req) => ({
    return {
      ...req,
      url: "https://nxs-api.xyz/api/proxy",
      headers: { ...(req.headers || {}),
        "x-fal-target-url": req.url,
      },
    },
  });
});


const result = await fal.run("fal-ai/flux/dev", {
  input: { prompt: "A cyberpunk city at sunset" },
});

SDK (Server)

Hono, Express, Node.js

REST API

Direct HTTP, any language

Server-Side

Node.js / Hono / Express

The fal SDK's proxyUrl is a browser-only feature. On the server, use requestMiddleware to route requests through NXS API, or call the REST API directly.

Option A — requestMiddleware (SDK-compatible)

server.ts

import { fal } from "@fal-ai/client";

fal.config({
  credentials: "nxs_your_api_key",
  requestMiddleware: async (req) => ({
    ...req,
    url: "https://nxs-api.xyz/api/proxy",
    headers: {
      ...(req.headers || {}),
      "x-fal-target-url": req.url,
    },
  }),
});

// All fal.run(), fal.subscribe(), etc. work as-is
const result = await fal.run("fal-ai/flux/dev", {
  input: { prompt: "A cyberpunk city at sunset" },
});

Option B — Direct REST API

server.ts

const result = await fetch("https://nxs-api.xyz/fal-ai/flux/dev", {
  method: "POST",
  headers: {
    "Authorization": "Key nxs_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "A cyberpunk city at sunset" }),
});

const data = await result.json();
console.log(data.images[0].url);

Hono example

app.ts

import { Hono } from "hono";
import { fal } from "@fal-ai/client";

const app = new Hono();

fal.config({
  credentials: process.env.NXS_API_KEY,
  requestMiddleware: async (req) => ({
    ...req,
    url: "https://nxs-api.xyz/api/proxy",
    headers: {
      ...(req.headers || {}),
      "x-fal-target-url": req.url,
    },
  }),
});

app.get("/generate", async (c) => {
  const result = await fal.run("fal-ai/flux/dev", {
    input: { prompt: "A cyberpunk city at sunset" },
  });
  return c.json(result);
});

export default app;

REST API

Direct HTTP Requests

The simplest integration — works with any language or framework. Just send a POST request with your nxs_ key in the Authorization header.

Endpoint format

endpoint

POST https://nxs-api.xyz/{model_path}

Headers:
  Authorization: Key nxs_your_api_key
  Content-Type: application/json

Body:
  JSON payload (same as fal.ai)

cURL

terminal

curl -X POST https://nxs-api.xyz/fal-ai/flux/dev \
  -H "Authorization: Key nxs_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A beautiful sunset over mountains"}'

Queue API (async)

terminal

# Submit a job
curl -X POST https://nxs-api.xyz/queue/fal-ai/flux/dev \
  -H "Authorization: Key nxs_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}'

# Check status
curl https://nxs-api.xyz/queue/fal-ai/flux/dev/requests/{request_id}/status \
  -H "Authorization: Key nxs_your_api_key"

# Get result
curl https://nxs-api.xyz/queue/fal-ai/flux/dev/requests/{request_id} \
  -H "Authorization: Key nxs_your_api_key"

API Reference

Authentication

Header	Authorization: Key nxs_...
Alt Header	Authorization: Bearer nxs_...
Key Prefix	nxs_

URL Patterns

Your Request	Forwards To
/fal-ai/flux/dev	fal.run/fal-ai/flux/dev
/xai/grok-imagine-image	fal.run/xai/grok-imagine-image
/queue/fal-ai/flux/dev	queue.fal.run/fal-ai/flux/dev
/flux/dev	fal.run/fal-ai/flux/dev

Error Codes

Status	Meaning
401	Missing or invalid API key
402	Subscription not active
413	Request body too large (max 50MB)
502	All upstream keys failed — try again later
503	No upstream keys configured