Hormouz API Documentation

Code Examples

Your first request

Drop-in compatible with the OpenAI SDK. Point it at Hormouz and start building.

from openai import OpenAI

client = OpenAI(
    api_key="ng-YOUR_KEY",
    base_url="https://api.hormouz.net/v1",
)

resp = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)

curl https://api.hormouz.net/v1/chat/completions \
  -H "Authorization: Bearer ng-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "ng-YOUR_KEY",
  baseURL: "https://api.hormouz.net/v1",
});

const resp = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);

Core Concepts

How it works

Understand the key building blocks before diving into the API reference.

Chat Completions

Send messages to any LLM and get a response. Supports streaming for real-time chat UIs, tool/function calling, vision (image inputs), and all OpenAI SDK features. Use POST /v1/chat/completions.

Image Generation

Generate images with FLUX, Stable Diffusion, and other models via an async prediction flow. Create a prediction, poll for completion, then download the mirrored output. Use POST /v1/predictions.

Model Catalogue

Browse 350+ models with pricing, capabilities, and the API shape to use. Check api_shape to know whether to call /v1/chat/completions or /v1/predictions. Use GET /v1/models.

Credit Billing

A hold is placed before each request. After completion, the actual cost is settled and the difference is released. If your balance is too low, the request returns 402. Check your balance in the dashboard.

Content Policy

You own what you send. Hormouz is a gateway — we don't moderate or approve your content. We offer an on-demand moderation API (POST /v1/moderations/image) with 3 classifier models at different price points ($0.001–$0.015 per call). You can also opt in to automatic pre-flight screening on image-only models (contact support to enable). See GET /v1/moderation-models for available classifiers and pricing.

Text Embeddings

Convert text into vector representations for search, clustering, and similarity. OpenAI-compatible — use your existing SDK with POST /v1/embeddings. Supports single strings and batch arrays. Cost is settled instantly from the upstream response.

Optimise for Cost or Speed

Many models can be served several ways, at very different prices and speeds. Add "sorted_by": "cheapest" | "latency" | "throughput" to a chat request and it is routed accordingly — cheapest per token, fastest first token, or highest tokens per second. Ranking follows live traffic, so it tracks current conditions and temporary discounts. It is a preference, not a guarantee: if the best option is busy, the next one serves it instead of failing. Note that a sorted request bills at the model's standard list price — any discounted route the model normally takes is skipped for that request. Any other value is rejected with 400 INVALID_SORTED_BY. Models where it applies are marked supports_sorted_by in GET /v1/models.

Error Reference

Error codes

All errors return a JSON envelope with code, message, and status. Match the code field in your error handling.

Status	Code	Meaning
400	`BAD_REQUEST`	Invalid request body or parameters
401	`UNAUTHORIZED`	Missing or invalid API key
402	`INSUFFICIENT_CREDITS`	Not enough credit balance
404	`NOT_FOUND`	Resource not found or not owned by you
409	`CONFLICT`	Idempotency key conflict
429	`RATE_LIMITED`	Too many requests, slow down
451	`CONTENT_POLICY_VIOLATION`	Image flagged by content policy (NSFW/explicit)
503	`UPSTREAM_ERROR`	Provider temporarily unavailable, retry with backoff

API Documentation

Connect in 30 seconds