appnz-gateway-api

name	appnz-gateway-api
description	Use this skill for app.nz's OpenAI-compatible AI gateway, model routing, app/auto models, fallback chains, BYOK provider keys, usage billing, and calling chat, images, embeddings, speech, transcription, video, music, 3D, and MCP endpoints through https://app.nz.

app.nz Gateway API

Use the OpenAI-compatible gateway at https://app.nz/v1 with an app.nz API key. Prefer app/auto for general work, then pin a provider model only when the user asks for a specific backend or capability.

Workflow

1. Set APPNZ_API_KEY or use the user's provided bearer token. Never ask the user to paste upstream provider keys into chat.
2. Discover models with GET /api/gateway/models when model availability matters.
3. Use app/auto, app/auto-code, app/auto-fast, app/auto-cheap, app/auto-reasoning, app/auto-vision, or app/auto-image before pinning a provider model.
4. For BYOK, store the upstream key once with /api/gateway/provider-keys; normal /v1/* calls then use it automatically.
5. Inspect spend with GET /api/usage or GET /api/gateway/usage.

Endpoints

• GET /api/gateway/models or /api/models: model catalogue with provider, modality, pricing, context, and capabilities.
• GET /api/gateway/resolve?model=...: show provider routing, provider model id, base URL, key env, and fallback chain.
• POST /v1/chat/completions: OpenAI-compatible chat, streaming, tools, and auto-routing.
• POST /v1/messages: Anthropic-compatible messages.
• POST /v1/images/generations, /v1/embeddings, /v1/audio/speech, /v1/audio/transcriptions.
• POST /v1/videos/generations, /v1/videos/edits, /v1/videos/extensions, /v1/music/generations, /v1/3d/generations.
• POST /mcp or /v1/mcp: MCP tools over the same auth and billing.

MCP Relation

/mcp and /v1/mcp are JSON-RPC MCP transports for the same app.nz account and gateway. MCP tool calls such as chat, list_models, generate_image, and embed dispatch in-process to the existing gateway handlers, so BYOK key selection, fallback routing, usage metering, and billing are shared with /v1/*. The separate /api/mcp-servers surface is a directory/search API for external MCP servers; it is not the app.nz MCP transport itself.

Quick Call

curl -s https://app.nz/v1/chat/completions \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model":"app/auto","messages":[{"role":"user","content":"Explain CRDTs briefly."}]}'

Python:

import os
from openai import OpenAI

client = OpenAI(base_url="https://app.nz/v1", api_key=os.environ["APPNZ_API_KEY"])
response = client.chat.completions.create(
    model="app/auto-code",
    messages=[{"role": "user", "content": "Write a TypeScript debounce function."}],
)
print(response.choices[0].message.content)

Providers

This snapshot covers 180 models across 23 providers: anthropic, appnz, cursor, cutedsl, deepseek, exa, fal, fireworks, gobed, google, groq, minimax, mistral, netwrck, nous, nvidia, openai, openrouter, papers, textgenerator, together, xai, zai.