provocapi

Migrating from OpenAI

provocapi is a drop-in replacement for the OpenAI API. If your code uses the official OpenAI Python or JavaScript SDK, you can switch by changing two lines.

What changes

	OpenAI	provocapi
Base URL	`https://api.openai.com/v1`	`https://inference.provocative.earth/v1`
API key prefix	`sk-`	`pk-prov-`
Models	`gpt-4o`, `text-embedding-3-large`	`llama-3.1-70b-instruct`, `bge-m3`

What doesn’t change

Request/response format — identical JSON shapes for chat completions, completions, embeddings, and model listing.
Streaming — same SSE format, same [DONE] sentinel.
Tool/function calling — supported on chat models that have it (Llama 3.1, Qwen 2.5).
JSON mode — pass response_format: {"type": "json_object"} and it works via grammar-constrained decoding.
Error format — same {"error": {"message": ..., "type": ..., "code": ...}} shape.
SDK methods — client.chat.completions.create(), client.embeddings.create(), client.models.list() all work unchanged.

Python migration

  from openai import OpenAI

  client = OpenAI(
-     # defaults to OPENAI_API_KEY env var
+     base_url="https://inference.provocative.earth/v1",
+     api_key="pk-prov-YOUR-KEY",  # or set OPENAI_API_KEY
  )

  response = client.chat.completions.create(
-     model="gpt-4o",
+     model="llama-3.1-70b-instruct",
      messages=[{"role": "user", "content": "hello"}],
  )

Alternatively, set environment variables and change nothing in code:

export OPENAI_BASE_URL=https://inference.provocative.earth/v1
export OPENAI_API_KEY=pk-prov-YOUR-KEY

JavaScript migration

  import OpenAI from "openai";

  const client = new OpenAI({
+   baseURL: "https://inference.provocative.earth/v1",
+   apiKey: "pk-prov-YOUR-KEY",
  });

Model mapping

Use this table to find the provocapi equivalent of the OpenAI model you’re currently using:

OpenAI model	provocapi equivalent	Notes
`gpt-4o`	`llama-3.1-70b-instruct`	Comparable on most benchmarks, 30-50% cheaper
`gpt-4o-mini`	`llama-3.1-8b-instruct`	Fast, cheap, good for routing/classification
`gpt-4-turbo`	`qwen-2.5-72b-instruct`	Strong multilingual and coding
`gpt-3.5-turbo`	`mistral-small-3-24b`	Mid-tier, good general purpose
`text-embedding-3-large`	`bge-m3`	1024-dim, multilingual
`text-embedding-3-small`	`nomic-embed-v1.5`	768-dim, fast, cheap

Features not yet supported

These OpenAI features are not available on provocapi v1. Plan accordingly:

Assistants API (threads, runs, file search) — we’re inference-only, not a RAG product
Image generation (DALL-E) — not on our roadmap
Audio (Whisper, TTS) — coming in v1.5
Vision (image inputs) — coming in v1.5 with Llama 3.2 Vision
Fine-tuning API — bring your own LoRA weights instead (see LoRA Adapters)
Moderation endpoint — not provided
Realtime API (WebRTC) — not provided

Response headers

provocapi adds observability headers to every response that OpenAI doesn’t include:

Header	Description
`X-Request-Id`	Unique request ID for tracing
`X-Provocapi-Worker`	Which backend worker served the request
`X-Provocapi-Queue-Ms`	Time spent in the routing queue
`X-Provocapi-Model`	Resolved model ID

Your existing code will ignore these (they’re custom headers), but they’re useful for debugging latency issues.