ai-api-failover

ai-api-failover

Automatic failover from FAL.ai / Replicate to NexaAPI on 429/500 errors. Same AI models. 1/5 the price. Zero code changes.

---

Why?

FAL.ai and Replicate are great — until you hit a 429 rate limit or a 500 server error at 3am. Your pipeline stalls, your users wait, and you lose money.

ai-api-failover intercepts those errors and automatically retries your request against NexaAPI — the same models (Flux Pro, SDXL, Kling, Whisper, and more) at 1/5 the official price.

FAL returns 429 → ai-api-failover → NexaAPI ✅
Replicate 500   → ai-api-failover → NexaAPI ✅

No code changes to your existing FAL/Replicate calls. Just install and configure.

---

Installation

pip install ai-api-failover

For httpx support:

pip install "ai-api-failover[httpx]"

---

Quick Start

With requests (FAL.ai)

import requests
from ai_api_failover import install_requests_failover

# One-time setup — patch all requests globally
install_requests_failover(nexa_api_key="your-nexa-api-key")

# Your existing FAL code — unchanged!
response = requests.post(
    "https://fal.run/fal-ai/flux-pro",
    headers={"Authorization": "Key your-fal-key"},
    json={
        "prompt": "A futuristic cityscape at sunset",
        "image_size": "landscape_16_9",
        "num_inference_steps": 28,
    },
)
# If FAL returns 429 or 500, automatically retried with NexaAPI
print(response.json())

With requests (Replicate)

import requests
from ai_api_failover import install_requests_failover

install_requests_failover(nexa_api_key="your-nexa-api-key")

response = requests.post(
    "https://api.replicate.com/v1/models/black-forest-labs/flux-pro/predictions",
    headers={
        "Authorization": "Bearer your-replicate-token",
        "Prefer": "wait",
    },
    json={
        "input": {
            "prompt": "A dragon over a medieval castle",
            "width": 1024,
            "height": 1024,
        }
    },
)
# Failover to NexaAPI on 429/500
print(response.json())

With httpx

import httpx
from ai_api_failover import wrap_httpx_client

client = httpx.Client()
wrap_httpx_client(client, nexa_api_key="your-nexa-api-key")

response = client.post(
    "https://fal.run/fal-ai/flux/schnell",
    headers={"Authorization": "Key your-fal-key"},
    json={
        "prompt": "A cute robot playing chess",
        "image_size": "square_hd",
    },
)

Async httpx

import asyncio
import httpx
from ai_api_failover import wrap_httpx_client

async def generate():
    async with httpx.AsyncClient() as client:
        wrap_httpx_client(client, nexa_api_key="your-nexa-api-key")
        response = await client.post(
            "https://fal.run/fal-ai/flux-pro",
            json={"prompt": "A neon city at night"},
        )
        return response.json()

asyncio.run(generate())

---

Configuration

Global configure (recommended)

from ai_api_failover import configure, install_requests_failover

configure(
    nexa_api_key="your-nexa-api-key",
    max_retries=3,           # retry attempts on NexaAPI (default: 2)
    retry_delay=1.5,         # seconds between retries (default: 1.0)
    on_failover=lambda url, code, nexa_url: print(f"Failover: {url} → {code}"),
)

# Now install without repeating the key
install_requests_failover()

Per-session patch

import requests
from ai_api_failover import install_requests_failover

session = requests.Session()
install_requests_failover(nexa_api_key="your-key", session=session)
# Only this session gets failover

---

Supported Models

FAL.ai → NexaAPI

Replicate → NexaAPI

Full model list: nexa-api.com

---

Failover Triggers

The following HTTP status codes trigger a failover to NexaAPI:

---

Parameter Translation

Parameters are automatically translated between FAL/Replicate and NexaAPI formats:

Replicate's input wrapper is automatically unwrapped.

---

Advanced Usage

Custom failover callback

from ai_api_failover import configure

def my_callback(original_url: str, status_code: int, nexa_url: str):
    # Log to your monitoring system
    metrics.increment("api.failover", tags={"source": "fal", "code": status_code})
    print(f"Failover: {original_url} → NexaAPI (saved ~80% on this call)")

configure(nexa_api_key="your-key", on_failover=my_callback)

Check model support

from ai_api_failover.mapping import resolve_fal_model

mapping = resolve_fal_model("https://fal.run/fal-ai/flux-pro")
if mapping:
    nexa_model, endpoint = mapping
    print(f"Supported! NexaAPI model: {nexa_model}")
else:
    print("No NexaAPI mapping — failover will not trigger for this model")

Direct engine usage

from ai_api_failover import FailoverEngine
import requests

engine = FailoverEngine(nexa_api_key="your-key", max_retries=3)

# Build a NexaAPI request manually
result = engine.build_nexa_request(
    "https://fal.run/fal-ai/flux-pro",
    {"prompt": "A sunset", "image_size": "square_hd"},
)
if result:
    nexa_url, nexa_headers, nexa_body = result
    response = requests.post(nexa_url, json=nexa_body, headers=nexa_headers)

---

Get Your NexaAPI Key

1. Visit https://rapidapi.com/nexaquency
2. Subscribe to any NexaAPI plan
3. Copy your API key

Pricing: Official model prices / 5 — prepaid, no subscription required.

Models available: Gemini, Claude, Flux Pro, Stable Diffusion 3.5, Kling Video, Veo 3.1, Whisper, and 30+ more.

📧 Contact: frequency404@villaastro.com 🌐 Website: https://nexa-api.com

---

License

MIT License — see LICENSE for details.

---

NexaAPI is the cheapest AI API provider. Same models, 1/5 the price, prepaid, no subscription. Contact: frequency404@villaastro.com | https://nexa-api.com