Architecture
Headless AI API engine
The platform runs as a ShipAny Next module stack: thin routes, standalone service functions, shared core infrastructure, and configurable provider routing.
Public API
/api/v1 routes authenticate API keys, normalize requests, and return compatible responses.
Console
Settings pages expose API keys, usage, credits, billing, and account data to the owner.
Admin
Admin pages configure models, channels, upstream cost rules, users, and finance summaries.
Jobs
Internal job routes process media tasks, callbacks, stale work, channel health, and retention cleanup.
Providers
Adapters convert platform requests into upstream provider requests and normalize results.
Request lifecycle
Authenticate and scope
API keys are hashed at rest, loaded by bearer token, and checked for owner, status, model scope, RPM, and project budget.
Precheck credits
The platform estimates required credits, checks user balance, and blocks calls that cannot be paid safely.
Route upstream
Model channel groups, channel health, priority, weight, provider mapping, and fallback policy determine the upstream attempts.
Settle credits
Successful sync calls charge credits; async media reserves credits at task creation and refunds terminal failures through the ledger.
Audit and retain
Usage rows, attempt rows, task rows, callback state, upstream cost, and monthly summaries support user accounting and operator debugging.
Extension rules
Add a model
Create an API Model with public id, request type, pricing, parameters, fallback policy, and channel groups.
Add a channel
Create an API Channel with provider, base URL, secret reference, supported types, health status, priority, and weight.
Add cost rules
Create API Cost rules per channel and model pattern so finance pages can compute upstream spend and margin.
Add a provider adapter
Only add code when an upstream protocol cannot be represented by the existing OpenAI-compatible, Gemini, or task-based media adapters.