API Reference

Complete guide to integrating NavyAI's unified API for chat, embeddings, image generation, and more.

OpenAI Compatible

Drop-in replacement

150+ Models

One endpoint

Low Latency

Optimized routing

Base URL

https://api.navy/v1

Introduction

Get started with the NavyAI API in minutes.

NavyAI provides a unified API that gives you access to 150+ AI models from multiple providers through a single, OpenAI-compatible interface. Simply swap your base URL and start using any model instantly.

Quick Start

Get started in minutes by using the OpenAI SDK with your NavyAI API key:

Get your API key from the Dashboard
Set the base URL to https://api.navy/v1
Start making requests!

Authentication

Secure your API requests with authentication.

All API requests require authentication using an API key. Include your API key in the Authorization header of every request.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Get Your API Key

You can obtain your API key from the NavyAI Dashboard. Keep your API key secure and never share it publicly.

Chat Completions

Create conversational AI interactions with advanced language models.

POST/v1/chat/completions

Create chat completions using advanced language models. Supports streaming, multi-turn conversations, vision (image inputs), web search, tool/function calling, and various parameters for controlling output.

Code Examples

curl -X POST "https://api.navy/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Tell me a fun fact."}]
  }'

Parameters

Parameter	Type	Description
`model`required	`string`	Model ID to use (e.g., gpt-5.2, claude-sonnet-4.5). Append ":search" for web search (e.g., "gpt-4o:search")
`messages`required	`array`	List of message objects with role and content. Content can be a string or an array of parts (text, image_url) for vision models
`max_tokens`optional	`integer`	Maximum tokens to generate
`temperature`optional	`number`	Sampling temperature (0.0-2.0)
`top_p`optional	`number`	Nucleus sampling threshold (0.0-1.0)
`top_k`optional	`integer`	Top-K sampling parameter (supported by some providers)
`stream`optional	`boolean`	Enable streaming responses
`stop`optional	`string \| array`	Stop sequence(s) to end generation
`seed`optional	`integer`	Random seed for reproducible outputs (supported by some providers)
`frequency_penalty`optional	`number`	Penalize repeated tokens based on frequency (-2.0 to 2.0)
`presence_penalty`optional	`number`	Penalize tokens based on presence (-2.0 to 2.0)
`reasoning_effort`optional	`string`	Control thinking depth: "none", "minimal", "low", "medium", "high", "xhigh" (for thinking-capable models)
`response_format`optional	`object`	Force output format: { type: "json_object" }, { type: "json_schema", json_schema: {...} }, or { type: "text" }
`tools`optional	`array`	List of tool/function definitions for function calling
`tool_choice`optional	`string \| object`	Control tool usage: "auto", "none", "required", or { type: "function", function: { name: "..." } }

Vision Support

Many models support image inputs via the image_url content type in messages:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What's in this image?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } }
  ]
}

Supports both URLs and base64 data URIs (data:image/png;base64,...).

Web Search

Append :search to any model name to enable real-time internet search. Search results are automatically injected into the context. Example: "model": "gpt-4o:search"

Embeddings

Generate vector embeddings for semantic search and similarity.

POST/v1/embeddings

Generate text embeddings for semantic search, clustering, and similarity comparisons.

Code Examples

curl -X POST "https://api.navy/v1/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "The quick brown fox jumps over the lazy dog"
  }'

Parameters

Parameter	Type	Description
`model`required	`string`	Embedding model ID (e.g., text-embedding-3-large)
`input`required	`string \| array`	Text or array of texts to embed
`encoding_format`optional	`string`	Return format: "float" or "base64"

Image Generation

Create stunning images from text descriptions.

POST/v1/images/generations

Generate images from text descriptions using state-of-the-art diffusion models. This endpoint also supports video generation models.

Code Examples

curl -X POST "https://api.navy/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "flux.1-schnell",
    "prompt": "A cute cat wearing a wizard hat",
    "n": 1,
    "size": "1024x1024"
  }'

Parameters

Parameter	Type	Description
`model`required	`string`	Image model ID (e.g., flux.1-schnell, dall-e-3, gpt-image-1.5)
`prompt`required	`string`	Text description of the desired image
`size`optional	`string`	Image resolution (e.g., "1024x1024") or aspect ratio (e.g., "16:9")
`image_url`optional	`string`	Input/reference image URL or base64 data URI for image editing, kontext, or video start frame
`negative_prompt`optional	`string`	Text describing what to avoid in the generated image
`seed`optional	`integer`	Random seed for reproducible generation
`quality`optional	`string`	Quality level: "low" or "medium" (model-dependent)
`style`optional	`string`	DALL·E 3 style: "vivid" or "natural"
`seconds`optional	`number`	Duration for video models (0-10 seconds)
`sync`optional	`boolean`	If false, returns job ID for async polling. Recommended for video models.

Asynchronous Generation

For video models or when sync: false, the API returns a job object:

{
  "id": "job_123...",
  "status": "queued",
  "created_at": 1715000000
}

Poll /v1/images/generations/{id} to check status.

Text-to-Speech

Convert text into natural-sounding speech audio.

POST/v1/audio/speech

Convert text to natural-sounding speech audio with multiple voice options.

Code Examples

curl -X POST "https://api.navy/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello world! This is a text to speech test.",
    "voice": "alloy"
  }' \
  --output speech.mp3

Parameters

Parameter	Type	Description
`model`required	`string`	TTS model ID (e.g., tts-1, tts-1-hd, eleven_v3, gpt-4o-mini-tts, gemini-2.5-flash-preview-tts)
`input`required	`string`	Text to convert to speech (max 4096 characters for ElevenLabs)
`voice`required	`string`	Voice preset. OpenAI: alloy, echo, fable, onyx, nova, shimmer. ElevenLabs: alice, aria, brian, etc. Gemini: Puck, Kore, etc.
`speed`optional	`number`	Playback speed (0.25 to 4.0, OpenAI models only)
`response_format`optional	`string`	Audio format: mp3, opus, aac, flac (OpenAI models)
`with-timestamps`optional	`boolean`	Return JSON with word-level timestamps (ElevenLabs models only)
`stability`optional	`number`	Voice stability (0.0-1.0, ElevenLabs models only)
`similarity_boost`optional	`number`	Voice similarity boost (0.0-1.0, ElevenLabs models only)

Speech-to-Text

Transcribe audio files into accurate text.

POST/v1/audio/transcriptions

Transcribe audio files into text with high accuracy across multiple languages.

Code Examples

curl -X POST "https://api.navy/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@/path/to/your/audio.mp3" \
  -F model="whisper-1"

Parameters

Parameter	Type	Description
`model`required	`string`	Transcription model (e.g., whisper-1, gpt-4o-transcribe, scribe_v2)
`file`required	`file`	Audio file to transcribe (max 25MB)
`language`optional	`string`	Input language in ISO-639-1 format
`response_format`optional	`string`	Output format: json, text, srt, vtt, verbose_json
`timestamp_granularities`optional	`array`	Timestamp detail level: ["word"], ["segment"], or both. Automatically sets response_format to verbose_json.

Moderations

Check content for policy violations.

POST/v1/moderations

Check text content for policy violations and harmful content.

Code Examples

curl -X POST "https://api.navy/v1/moderations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "text-moderation-stable",
    "input": "I want to check if this text is appropriate."
  }'

Parameters

Parameter	Type	Description
`model`optional	`string`	Moderation model: text-moderation-stable or text-moderation-latest
`input`required	`string \| array`	Text to check for policy violations

Create Response

Generate model responses with flexible inputs.

POST/v1/responses

Generate model responses with flexible input options and metadata support.

Code Examples

curl -X POST "https://api.navy/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "input": "Tell me a fun fact."
  }'

Parameters

Parameter	Type	Description
`model`required	`string`	Model ID to use for response generation
`input`required	`string \| object`	Text, image, or file inputs for the model
`stream`optional	`boolean`	Stream response as server-sent events
`instructions`optional	`string`	System message for model context
`max_output_tokens`optional	`integer`	Maximum tokens to generate
`metadata`optional	`object`	Key-value pairs for storing additional information

List Models

Retrieve available models and their details.

GET/v1/models

Retrieve a list of all available models and their details.

Code Examples

curl "https://api.navy/v1/models"

No Parameters Required

This endpoint does not require any parameters or authentication.

Usage Statistics

Track your API usage and token consumption.

GET/v1/usage

Get detailed usage statistics for your API key including request counts and token usage.

Code Examples

curl "https://api.navy/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

No Parameters Required

This endpoint does not require any parameters. Your API key determines which usage data is returned.