GET /v1/models
- -Returns the list of available models for your key. Published models: `deepseek-v4-flash`, `mimo-v2.5`, `qwen3.6`, `gemma4`, `qwen3-embedding`, `rerank`, `kokoro`, `whisper`, `flux-2-klein` (includes the `flux-2-klein` image model). `glm5.2` is served too, and is callable only with a key on the GLM 5.2 premium tier. - -### Request - -No body. Only the authentication header required. - -### Response - -```json -{ - "object": "list", - "data": [ - { - "id": "qwen3.6", - "object": "model", - "created": 1677610602, - "owned_by": "openai" - }, - { - "id": "gemma4", - "object": "model", - "created": 1677610602, - "owned_by": "openai" - } - ] -} -``` - -### Example - -```bash -curl https://api.nan.builders/v1/models \ - -H "Authorization: Bearer sk-your-key-here" -``` - -POST /v1/chat/completions
- -The main chat endpoint. OpenAI Chat Completions compatible. Compatible models: `deepseek-v4-flash`, `mimo-v2.5`, `qwen3.6`, `gemma4`, and `glm5.2`. `glm5.2` needs a key on the GLM 5.2 premium tier; the other models are available to every inference member. - -POST /v1/completions
- -Endpoint legacy de OpenAI para text completion. Compatible model: `qwen3.6`. - -### Request - -| Field | Type | Description | -|---|---|---| -| `model` | string · required | `qwen3.6`. | -| `prompt` | string · required | The prompt to complete. | -| `max_tokens` | integer · optional | Maximum tokens to generate. | -| `temperature` | number · optional | Default `0.6`. | -| `top_p` | number · optional | Default `0.95`. | -| `stream` | boolean · optional | Default `false`. | - -### Response - -```json -{ - "id": "cmpl-...", - "object": "text_completion", - "created": 1778258166, - "model": "qwen3.6", - "choices": [ - { - "text": "...", - "index": 0, - "finish_reason": "stop", - "logprobs": null - } - ], - "usage": { - "completion_tokens": 10, - "prompt_tokens": 5, - "total_tokens": 15 - } -} -``` - -### Example - -```bash -curl https://api.nan.builders/v1/completions \ - -H "Authorization: Bearer sk-your-key-here" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "qwen3.6", - "prompt": "The capital of France is", - "max_tokens": 10 - }' -``` - -### Notes - -Endpoint legacy de OpenAI. Para conversaciones, usa [/v1/chat/completions](#chat-completions). - -POST /v1/embeddings
- -Genera embeddings vectoriales. Compatible model: `qwen3-embedding`. Vectores de **4096 dimensiones**. - -### Request - -| Field | Type | Description | -|---|---|---| -| `model` | string · required | `qwen3-embedding`. | -| `input` | string \| array · required | Single text or array of strings to embed. | -| `encoding_format` | string · optional | `"float"` (default) o `"base64"`. | - -### Response - -```json -{ - "object": "list", - "model": "qwen3-embedding", - "data": [ - { - "object": "embedding", - "index": 0, - "embedding": [0.0210, 0.0105, -0.0204, "..."] - } - ], - "usage": { - "prompt_tokens": 3, - "total_tokens": 3 - } -} -``` - -### Example - -```bash -curl https://api.nan.builders/v1/embeddings \ - -H "Authorization: Bearer sk-your-key-here" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "qwen3-embedding", - "input": ["Hola mundo", "Hello world"] - }' -``` - -POST /v1/rerank
- -Reordena una lista de documentos por relevancia a una query. Compatible model: `rerank` (`Qwen3-Reranker-8B`). Completa el stack RAG junto a `qwen3-embedding`: primero recuperas top-K por embeddings, después reordenas con `rerank`. Soporta 100+ idiomas, recuperación de código y búsqueda cross-lingual. Endpoint alias: `/v2/rerank`. - -### Request - -| Field | Type | Description | -|---|---|---| -| `model` | string · required | `rerank`. | -| `query` | string · required | Query against which each document's relevance is measured. | -| `documents` | array · required | Array de strings a reordenar. La respuesta los returns ordenados de mayor a menor `relevance_score` con su `index` original. | -| `top_n` | integer · optional | Limita la respuesta a los `N` documentos más relevantes. Por defecto returns todos. | - -### Response - -```json -{ - "id": "score-a032ee5767cab0ee", - "results": [ - { - "index": 0, - "relevance_score": 0.7390941977500916, - "document": { - "text": "Paris is the capital of France." - } - }, - { - "index": 1, - "relevance_score": 0.6002889275550842, - "document": { - "text": "Berlin is the capital of Germany." - } - }, - { - "index": 2, - "relevance_score": 0.12374333292245865, - "document": { - "text": "Madrid is the capital of Spain." - } - } - ], - "meta": { - "billed_units": { - "total_tokens": 43 - }, - "tokens": { - "input_tokens": 43 - } - } -} -``` - -La respuesta incluye `id`, `results` (array de `{index, relevance_score, document}`) y `meta` con `billed_units` y conteo de tokens. `relevance_score` está en el rango [0, 1]. El `index` se refiere a la posición original del documento en el array de entrada. - -### Example - -```bash -curl https://api.nan.builders/v1/rerank \ - -H "Authorization: Bearer sk-your-key-here" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "rerank", - "query": "What is the capital of France?", - "documents": [ - "Paris is the capital of France and home to the Eiffel Tower.", - "Berlin is the capital of Germany.", - "Madrid is the capital of Spain." - ] - }' -``` - -Con el SDK de `openai` de Python (usando `post` directo, ya que `rerank` no forma parte del cliente OpenAI): - -```python -import os -from openai import OpenAI - -client = OpenAI( - api_key=os.environ["NAN_API_KEY"], - base_url="https://api.nan.builders/v1" -) - -response = client.post( - path="/rerank", - cast_to=object, - body={ - "model": "rerank", - "query": "What is the capital of France?", - "documents": [ - "Paris is the capital of France and home to the Eiffel Tower.", - "Berlin is the capital of Germany.", - "Madrid is the capital of Spain.", - ], - }, -) - -for r in response["results"]: - print(r["index"], r["relevance_score"]) -``` - -POST /v1/audio/speech
- -Synthesizes audio from text (text-to-speech). Compatible model: `kokoro`. - -### Request - -| Field | Type | Description | -|---|---|---| -| `model` | string · required | `kokoro`. | -| `input` | string · required | Text to synthesize. | -| `voice` | string · required | Voice to use. Some options: `af_heart` (English female), `ef_dora` (Spanish female), `em_alex` (Spanish male). [See full list](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md). | -| `response_format` | string · optional | Format of the returned audio. Validated: `mp3` (default), `wav`, `flac`, `aac`, `pcm`, `opus`. | -| `speed` | number · optional | Default `1.0`. | - -### Response - -Binary audio file in the requested format (without JSON wrapper). - -### Example - -```bash -curl https://api.nan.builders/v1/audio/speech \ - -H "Authorization: Bearer sk-your-key-here" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "kokoro", - "input": "Bienvenido a NaN.", - "voice": "ef_dora", - "response_format": "mp3" - }' \ - -o speech.mp3 -``` - -POST /v1/audio/transcriptions
- -Transcribes audio to text (speech-to-text). Compatible model: `whisper`. The request is `multipart/form-data`. - -### Request - -| Field | Type | Description | -|---|---|---| -| `file` | file · required | Audio file to transcribe. | -| `model` | string · required | `whisper`. | -| `language` | string · optional | ISO-639-1 code (ej. `es`, `en`). If not provided, detected automatically. | -| `response_format` | string · optional | Validated: `json` (default) y `verbose_json`. Other values work but return content wrapped in JSON; we recommend only these two. | -| `timestamp_granularities[]` | string · optional | Only with `verbose_json`. Valores: `word` (timestamps por palabra) o `segment` (default). | -| `temperature` | number · optional | Sampling temperature. | - -### Response - -Example with `response_format=verbose_json`: - -```json -{ - "text": "Hola, esto es una prueba.", - "language": "es", - "task": "transcribe", - "duration": 1.728, - "segments": [ - { - "id": 1, - "start": 0.0, - "end": 1.4, - "text": " Hola, esto es una prueba.", - "tokens": [50365, 22637, "..."], - "avg_logprob": -0.059, - "compression_ratio": 0.806, - "no_speech_prob": 0.044, - "temperature": 0.0 - } - ], - "words": null -} -``` - -If you pass `timestamp_granularities[]=word`, el campo `words` is populated with `[{word, start, end, probability}]`. - -### Example - -```bash -curl https://api.nan.builders/v1/audio/transcriptions \ - -H "Authorization: Bearer sk-your-key-here" \ - -F "model=whisper" \ - -F "file=@grabacion.mp3" \ - -F "language=es" \ - -F "response_format=verbose_json" -``` - -### Limitations - -OGG/Opus y MP3 — mejor compresión, misma calidad de transcripción.',
- },
- ]}
-/>
-
-POST /v1/responses
- -OpenAI-style Responses endpoint. Modelos compatibles: `qwen3.6` y `gemma4`. - -### Request - -| Field | Type | Description | -|---|---|---| -| `model` | string · required | `qwen3.6` o `gemma4`. | -| `input` | string \| array · required | Single text or array of messages in OpenAI Responses format. | -| `max_output_tokens` | integer · optional | Default `65536` en `qwen3.6`. | -| `temperature` | number · optional | Default `0.6`. | -| `top_p` | number · optional | Default `0.95`. | -| `instructions` | string · optional | System instructions. | - -### Response - -The array `output` can contain blocks of type `reasoning` (solo `qwen3.6`) y `message`. - -```json -{ - "id": "resp_...", - "created_at": 1778258181, - "model": "qwen3.6", - "object": "response", - "status": "completed", - "output": [ - { - "id": "rs_...", - "type": "reasoning", - "summary": [], - "content": [ - { "type": "reasoning_text", "text": "..." } - ] - }, - { - "id": "msg_...", - "type": "message", - "role": "assistant", - "status": "completed", - "content": [ - { "type": "output_text", "text": "Hola.", "annotations": [] } - ] - } - ], - "usage": { - "input_tokens": 17, - "output_tokens": 118, - "total_tokens": 135 - } -} -``` - -### Example - -```bash -curl https://api.nan.builders/v1/responses \ - -H "Authorization: Bearer sk-your-key-here" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "qwen3.6", - "input": "Hola, ¿cómo estás?" - }' -``` - -### Notes - -Streaming on this endpoint currently delivers a single event `response.completed` at the end, not incremental chunks. For token-by-token streaming use [/v1/chat/completions](#chat-completions) con `stream: true`. - -POST /v1/images/generations
- -Generates images from text (text-to-image). Compatible with OpenAI's Images API. Compatible model: `flux-2-klein` (only model available today; the endpoint is designed to add more). The body is JSON. - -### Request - -| Field | Type | Description | -|---|---|---| -| `prompt` | string · required | Textual description of the image to generate. | -| `model` | string · optional | Default `flux-2-klein` (único modelo disponible). An unknown model returns `404` (`model_not_found`). | -| `n` | integer · optional | Number of images to generate, between `1` y `4`. Default `1`. A value greater than `4` returns `400`. | -| `size` | string · optional | Format `"ANCHOxALTO"` con both sides divisible by 16, each between 256 and 1536, and aspect ratio between 1:3 and 3:1. Standard values like `1024x1024`, `1536x1024` o `1024x1536` work. `"auto"` or omitted → `1024x1024`. | -| `response_format` | string · optional | `"url"` (default) o `"b64_json"`. Con `url` a temporary R2 link is returned valid ~60 minutos (same contract as OpenAI). Con `b64_json` the image bytes are returned inline as base64. | - -quality, style, background, moderation, output_format, output_compression y user, pero are ignored — Flux does not act on them. Además, stream: true is not supported y returns 400.
-POST /v1/images/edits
- -Generates an image from one or more reference images (image-to-image). Compatible with OpenAI's Images API. Compatible model: `flux-2-klein`. The request is `multipart/form-data`. Aplican la misma membresía inference-tier y la misma cuota mensual de 100 requests que [/v1/images/generations](#images-generations). - -### Request - -| Field | Type | Description | -|---|---|---| -| `image` / `image[]` | file · required | One or more reference images (up to 4; extras are discarded). PNG, JPEG, or WebP, each < 25 MB. | -| `prompt` | string · required | Description of the edit or transformation to apply. | -| `model`, `n`, `size`, `response_format` | optional | Same behavior as in [/v1/images/generations](#images-generations). Las extensiones `seed` y `guidance` are also accepted (as form fields). | - -mask is not supported y returns 400 — Flux Klein does not do inpainting.
-POST /v1/search
- -An authenticated web-search tool for your agents. You send a query and we return ranked results (title, URL, snippet, and optionally the page's readable content) through our API — your key never talks to a third-party search provider directly. Results come from a hybrid of an external search API (primary) and an internal fallback; you don't need to know which served a given request. - -Designed to be wired as an agent tool: give the model the [function schema below](#web-search-tool), and when it emits a `web_search` tool call, invoke this endpoint with the arguments and feed the JSON response back as the tool result. - -### Request - -The body is JSON. - -| Field | Type | Description | -|---|---|---| -| `query` | string · required | The search query. | -| `count` | integer · optional | Number of results to return, `1`–`20` (clamped). Default `5`. | -| `freshness` | string · optional | Recency filter: `pd` (past day), `pw` (past week), `pm` (past month), `py` (past year), or a `YYYY-MM-DDtoYYYY-MM-DD` date range. Omit for no time filter. | -| `fetch_content` | boolean · optional | When `true`, also fetch and include the readable text of the top results. Adds latency. Default `false` returns snippets only. | - -fetch_content is true, the server fetches page content only for the URLs the search engine returned, through a hardened anti-SSRF fetcher — you cannot pass an arbitrary URL to fetch.
-Wire it as an agent tool
- -Drop this into your model call's `tools` array (OpenAI-style function calling). When the model emits a `web_search` tool call, invoke `POST /v1/search` with the arguments and return the JSON response as the tool result. - -```json -{ - "type": "function", - "function": { - "name": "web_search", - "description": "Search the public web and return relevant results (title, URL, snippet, and optional page content). Use it when the answer may depend on current events, recent developments, prices, release/version numbers, or facts you are not confident are up to date.", - "parameters": { - "type": "object", - "properties": { - "query": { - "type": "string", - "description": "The web search query." - }, - "count": { - "type": "integer", - "description": "Number of results to return (1-20).", - "minimum": 1, - "maximum": 20, - "default": 5 - }, - "freshness": { - "type": "string", - "description": "Restrict results by recency: 'pd' (past day), 'pw' (past week), 'pm' (past month), 'py' (past year), or a 'YYYY-MM-DDtoYYYY-MM-DD' date range. Omit for no time filter." - }, - "fetch_content": { - "type": "boolean", - "description": "When true, also fetch and include the readable text of the top results (slower). Default false returns snippets only.", - "default": false - } - }, - "required": ["query"] - } - } -} -``` - -### Rate limits and quota - -Web search has its own limits, separate from the standard [rate limits](#rate-limits) of the model endpoints: searching does not consume your chat rpm budget, and vice versa. These limits are enforced per API key: - -| Limit | Value | Description | -|---|---|---| -| Rate limit | `20 req/min` | 20 requests per minute. Exceeding it returns `429` (`rate_limit_exceeded`); respect the `Retry-After` header. | -| Concurrency | `3` | Up to 3 concurrent searches. Exceeding it returns `429` (`rate_limit_exceeded`). | -| Daily quota | `500 / day` | 500 searches per day per API key. Exceeding it returns `429` (`insufficient_quota`). | - -### Search errors - -In addition to the [common errors](#errors), this endpoint may return: - -| Status | `code` | Description | -|---|---|---| -| 401 | `invalid_api_key` | The `Authorization` header is missing or the key is invalid. | -| 429 | `rate_limit_exceeded` | Per-minute or concurrency limit reached. Respect the `Retry-After` header. | -| 429 | `insufficient_quota` | Daily search quota exhausted. | -| 503 | `search_unavailable` | Search is temporarily unavailable; retry shortly. | - -MCP server
- -We expose a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so you can use our tools directly inside any MCP-compatible agent or client, authenticated with the **same** `sk-` API key as the REST API. The endpoint is `https://api.nan.builders/mcp` (Helmcode enterprise uses the same shape on `api.helmcode.com/mcp`). - -Today the server exposes a single tool, [`web_search`](#web-search) (same capability and arguments as `POST /v1/search`), and it is a growing registry — more tools will be added over time and appear automatically under `tools/list`. - -| Property | Value | -|---|---| -| Endpoint | `https://api.nan.builders/mcp` | -| Transport | Streamable HTTP (remote), stateless | -| Protocol | JSON-RPC 2.0 — methods: `initialize`, `tools/list`, `tools/call`, `ping` | -| Auth | `Authorization: Bearerweb_search tool call over MCP counts exactly like a POST /v1/search request.
-nan surfaces the tool as nan_web_search. A verbose name like nan-web-search would produce a duplicated-looking nan_web_search_web_search — name the entry nan.
-
- NaN
-
-
-
-
-