PRO-1 Documentation

PRO-1 is one evolving OpenAI-compatible model. Use pro-1 for the current production version, or pin an immutable dated snapshot such as pro-1-YYYY-MM-DD when your integration needs reproducible behavior. It works through /v1/chat/completions and the official OpenAI SDK — just change the base_url and the key.

Overview

PRO-1 adapts its processing to the difficulty of the task: simple requests are handled fast and cheap, complex ones get deeper processing and a completeness check on the result. From the outside it is an ordinary OpenAI-compatible model. Provider keys live on the server and are never handed to the consumer; requests are billed against your account balance.

Authentication

Protected generation and account endpoints require an API token in the Authorization header. Public endpoints such as /v1/estimate and /v1/benchmarks/* do not. Create a token in your account and keep it on the server (do not ship it in client-side code).

Authorization: Bearer <your-token>

MCP servers

PromanOS provides two remote stateless Streamable HTTP endpoints. The documentation endpoint is public and strictly read-only. The product endpoint accepts a PromanOS API token or, when the deployment has an OIDC provider configured, an OAuth 2.1 access token.

Docs MCP: https://api.promanos.com/mcp/docs — search/fetch public documentation, inspect the public OpenAPI contract, changelog and benchmark methodology.

Product MCP: https://api.promanos.com/mcp — PRO-1 and Marketplace tools. Order, accept and cancel actions are state-changing and must require explicit approval.

https://api.promanos.com/mcp/docs
https://api.promanos.com/mcp  # Authorization: Bearer <your-token>

OAuth scopes are pro1:invoke, marketplace:read, orders:read and orders:write. The server verifies signature, issuer, audience, expiry and scopes and publishes RFC 9728 discovery only when a real OIDC authorization server passes the live conformance gate. Safe readiness: GET /mcp/oauth/status.

Quickstart

curl https://api.promanos.com/v1/chat/completions \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "pro-1",
    "messages": [{"role": "user", "content": "Assess the launch strategy and surface any overlooked risks."}]
  }'

# pip install openai
from openai import OpenAI

client = OpenAI(base_url="https://api.promanos.com/v1", api_key="sk-...")
resp = client.chat.completions.create(
    model="pro-1",
    messages=[{"role": "user", "content": "Assess the launch strategy and surface any overlooked risks."}],
)
print(resp.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.promanos.com/v1", apiKey: process.env.PROMANOS_API_KEY });
const resp = await client.chat.completions.create({
  model: "pro-1",
  messages: [{ role: "user", content: "Assess the launch strategy and surface any overlooked risks." }],
});
console.log(resp.choices[0].message.content);

Chat Completions

POST /v1/chat/completions — the primary endpoint.

Response

An OpenAI-compatible object. Plus a neutral promanos block (model version, price, cache) and cost.

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "pro-1",
  "choices": [{ "message": { "role": "assistant", "content": "...full answer..." }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 120, "completion_tokens": 1720, "total_tokens": 1840 },
  "system_fingerprint": "promanos-pro-1",
  "promanos": {
    "model_version": "1.1.3",
    "price_usd": 0.41,
    "billing": {
      "pricing_version": "pro-1-usd-2026-07-11-r2",
      "billing_basis": "processed_tokens",
      "input_per_1m_usd": 12.0,
      "output_per_1m_usd": 48.0
    },
    "cached": false
  }
}

Streaming

With "stream": true the response arrives as text/event-stream (SSE) in chat.completion.chunk chunks. Each chunk may carry a neutral progress block (phase + short status); the final chunk carries usage + promanos. The stream ends with the line data: [DONE].

{ "object": "chat.completion.chunk", "model": "pro-1",
  "choices": [{ "delta": { "content": "..." }, "finish_reason": null }],
  "progress": { "event": "progress", "status_text": "Processing the request…" } }

For long-running tasks there is an asynchronous session API (POST /v1/chat/sessions + SSE /events or paged /events-page) — with a ready-made UI: Chat (progress bar, step feed, live cost).

Multimodal input. content can carry more than text: image_url (image analysis), input_audio (speech is transcribed to text), file (txt/csv/code/PDF — text is extracted) and input_video (video is analyzed frame by frame + speech is transcribed from the track). All of this is handled automatically by the model; extra processing is billed as added tokens.

Async sessions

Use the session API for long-running work, progress UI, cost approval, or clarification. Create a session with POST /v1/chat/sessions, consume events from the SSE /events stream (or recover with /events-page), then fetch the final OpenAI-compatible response from /result.

curl -X POST https://api.promanos.com/v1/chat/sessions \
  -H "Authorization: Bearer $PROMANOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"pro-1","messages":[{"role":"user","content":"Assess the launch strategy and surface any overlooked risks."}]}'

# SSE progress stream
curl -N https://api.promanos.com/v1/chat/sessions/SESSION_ID/events \
  -H "Authorization: Bearer $PROMANOS_API_KEY"

# Recovery-safe page and final response
curl "https://api.promanos.com/v1/chat/sessions/SESSION_ID/events-page?after=-1&limit=100" \
  -H "Authorization: Bearer $PROMANOS_API_KEY"
curl https://api.promanos.com/v1/chat/sessions/SESSION_ID/result \
  -H "Authorization: Bearer $PROMANOS_API_KEY"

Interactive runs may pause at awaiting_approval or awaiting_user. Use /approve or /live-input and continue reading events. A transient polling failure does not cancel the run; reconnect using the last next_after value.

Cost estimate

POST /v1/estimate — a cost/time range before you run (without calling any providers). Pass model: "pro-1" or a registered dated snapshot.

curl -X POST https://api.promanos.com/v1/estimate \\
  -H "Content-Type: application/json" -d '{"model": "pro-1"}'

Image generation

POST /v1/images/generations — OpenAI-compatible image generation (the pro-1 model). The size is snapped to a supported aspect ratio (square / portrait / landscape). The response is a data array with b64_json or url.

Automatic model selection for the task. The system understands what is needed: for images with text (a logo, a poster, lettering) or higher quality it picks a stronger, more expensive model; for ordinary pictures it picks an economical one. The chosen tier is returned in promanos.tier (standard / premium). You can set it explicitly via quality ("high" / "low").

curl -X POST https://api.promanos.com/v1/images/generations \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"prompt": "poster with the text SALE 50%", "size": "1024x1024", "n": 1}'

Billing is by the actual generation cost (depends on the chosen tier); like every request, the response returns the charged price in the promanos block.

Video generation

Video generation is asynchronous (a job): POST /v1/videos/generations immediately returns an id and status: "queued", then you poll GET /v1/videos/generations/{id} until status: "completed" — the response then includes data[].url for the finished clip. The tier is matched to the task; the charge applies on completion.

curl -X POST https://api.promanos.com/v1/videos/generations \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"prompt": "a red cube slowly rotating on a table"}'
# -> {"id": "...", "status": "queued"}; then:
curl https://api.promanos.com/v1/videos/generations/ID -H "Authorization: Bearer $PROMANOS_API_KEY"

Video takes ~30 s or more to generate; billing is by actual cost (charged once on completion).

Speech synthesis

POST /v1/audio/speech — text-to-speech (OpenAI-compatible). Returns raw audio bytes (like the OpenAI SDK); the charged price is in the X-Promanos-Price-USD header. Parameters: input, voice, response_format (mp3/wav/…), optional instructions (delivery style) and backend ("openai" — the default, or "elevenlabs" for premium voices; for ElevenLabs voice is a voice_id).

curl -X POST https://api.promanos.com/v1/audio/speech \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"input": "Hi! This is PRO-1.", "voice": "alloy", "response_format": "mp3"}' --output speech.mp3

Speech recognition (STT)

POST /v1/audio/transcriptions — speech to text (JSON + base64 audio). With "stream": true the response arrives as a Server-Sent Events stream: transcript.text.delta events (as recognition proceeds) and a final transcript.text.done — live transcription.

curl -N -X POST https://api.promanos.com/v1/audio/transcriptions \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"file_data": "", "filename": "speech.mp3", "stream": true, "language": "ru"}'

Music generation

POST /v1/music/generations — generate music and songs from a text description (the pro-1 model). Returns raw audio bytes (mp3, 48 kHz); the charged price is in the X-Promanos-Price-USD header.

curl -X POST https://api.promanos.com/v1/music/generations \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"prompt": "an upbeat pop-rock chorus about summer"}' --output song.mp3

Files

Upload a file once and reuse it in later requests by file_id, and search it by content. Storage is tied to your account. On upload, text is extracted from the file (txt/csv/code/PDF).

# upload (JSON + base64)
curl -X POST https://api.promanos.com/v1/files \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"filename": "report.pdf", "file_data": ""}'   # -> {"id": "...", ...}
# Large files (up to 5 GiB): initialize, PUT raw 8 MiB parts, then complete.
curl -X POST https://api.promanos.com/v1/files/uploads \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/json" \\
  -d '{"filename":"huge.dat","bytes":5368709120}'
curl -X PUT https://api.promanos.com/v1/files/uploads/UPLOAD_ID/parts/0 \\
  -H "Authorization: Bearer $PROMANOS_API_KEY" -H "Content-Type: application/octet-stream" --data-binary @part-0
curl -X POST https://api.promanos.com/v1/files/uploads/UPLOAD_ID/complete \\
  -H "Authorization: Bearer $PROMANOS_API_KEY"
# list / metadata / download / delete
curl https://api.promanos.com/v1/files               -H "Authorization: Bearer $KEY"
curl https://api.promanos.com/v1/files/FILE_ID        -H "Authorization: Bearer $KEY"
curl https://api.promanos.com/v1/files/FILE_ID/content -H "Authorization: Bearer $KEY" --output file.bin
curl -X DELETE https://api.promanos.com/v1/files/FILE_ID -H "Authorization: Bearer $KEY"
# search by content
curl -X POST https://api.promanos.com/v1/files/search -H "Authorization: Bearer $KEY" \\
  -H "Content-Type: application/json" -d '{"query": "Q3 revenue"}'
# use in chat by id
# content: [{"type":"text","text":"..."}, {"type":"file","file":{"file_id":"FILE_ID"}}]

Realtime (real-time voice/text)

WebSocket wss://api.promanos.com/v1/realtime — a bidirectional real-time stream (voice and text, low latency). First request a short-lived ticket with POST /v1/realtime/ticket, then connect with ?ticket=…. This keeps the long-lived API key out of the WebSocket URL. Billing is finalized from actual usage at the end of the session.

// browser
const ticketRes = await fetch("https://api.promanos.com/v1/realtime/ticket", {
  method: "POST",
  headers: { Authorization: "Bearer " + API_KEY }
});
const { ticket } = await ticketRes.json();
const ws = new WebSocket("wss://api.promanos.com/v1/realtime?ticket=" + encodeURIComponent(ticket));
ws.onmessage = (e) => console.log(JSON.parse(e.data));   // session events
ws.onopen = () => ws.send(JSON.stringify({ type: "session.update", session: {
  type: "realtime",
  output_modalities: ["audio"],
  instructions: "Hello!",
  audio: {
    input: {
      format: { type: "audio/pcm", rate: 24000 },
      turn_detection: { type: "server_vad", create_response: true, interrupt_response: true }
    },
    output: { format: { type: "audio/pcm", rate: 24000 }, voice: "alloy" }
  }
} }));

Models

GET /v1/models lists the moving pro-1 id and immutable dated snapshots. The bare id always points to the current production version; pin pro-1-YYYY-MM-DD for reproducible behavior. GET /v1/models/pro-1 returns the current model card, version, and readiness.

Errors

Errors come back in the OpenAI-compatible format { "error": { "message", "type", "code" } }. The response header X-Request-ID and payload field request_id identify the failed request. Strict failure with no silent degradation: when a provider is unavailable you get an explicit error, never a quietly worse answer.

Pricing & limits

Prepaid pay as you go, with no subscription or promotional credits. Rates are $12 / 1M input · $48 / 1M output processed tokens. Processed tokens include internal model calls, reasoning, synthesis and verification, so they can exceed the visible prompt and answer size. Each response returns the exact charge and pricing version pro-1-usd-2026-07-11-r2 in promanos.billing. Use GET /v1/pricing as the machine-readable rate source and POST /v1/estimate for a pre-run cost range.

Questions: [email protected] · Try it live: Chat