OpenAI-compatible API
Run OpenAI clients against Nucleus models by changing only the base URL.
Point any OpenAI client at https://api.nucleus-ai.io/v1 and change nothing else. Existing
code, SDKs and tooling keep working; authenticate with your Nucleus key in place of an OpenAI
key. The model parameter accepts a base model ID from
List base models or a nucleus:// sampler-weights path such as
nucleus://run_3Bz:train:0/sampler_weights/000240, so the same client serves both base models
and your fine-tuned checkpoints.
Unlike the token-level sampling primitives, these routes render
text server-side: you send strings or conversation turns and never handle token IDs. Both
routes require the infer scope. For a setup walkthrough, see the
OpenAI compatibility guide.
Create a completion
/v1/completionsscope: inferReturns a raw text continuation of prompt. No chat template is applied: the prompt is
tokenized as-is and the model continues it. For conversational workloads, use
Create a chat completion instead.
Body parameters
modelstringrequiredBase model ID or a nucleus:// sampler-weights path.
promptstringrequiredThe text to continue.
max_tokensintegerMaximum number of tokens to generate.
temperaturenumberSampling temperature.
top_pnumberNucleus sampling threshold.
streambooleanWhen true, tokens are streamed over text/event-stream as they are generated. With cURL, add
-N to disable buffering.
curl https://api.nucleus-ai.io/v1/completions \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen3-8B",
"prompt": "The capital of France is",
"max_tokens": 8
}'{
"id": "cmpl_3xB",
"choices": [{ "text": " Paris.", "finish_reason": "stop" }],
"usage": { "prompt_tokens": 5, "completion_tokens": 3 }
}Create a chat completion
/v1/chat/completionsscope: inferThe recommended of the two OpenAI-compatible routes. Your messages are rendered with the
model's chat template server-side, so you send plain conversation turns and get a structured
assistant message back. If you need token-level control over sampling, for example inside a
reinforcement-learning loop, use
Generate samples instead.
Body parameters
modelstringrequiredBase model ID or a nucleus:// sampler-weights path.
messagesarrayrequiredThe conversation so far, as role and content objects.
max_tokensintegerMaximum number of tokens to generate.
temperaturenumberSampling temperature.
top_pnumberNucleus sampling threshold.
streambooleanWhen true, tokens are streamed over text/event-stream as they are generated. With cURL, add
-N to disable buffering.
separate_reasoningbooleandefault: trueWhen true, the model's reasoning is returned in a separate reasoning_content field on the
message rather than mixed into content.
reasoning_effortstring | numberHow much reasoning the model does before answering: a named level from none to xhigh, or a
float between 0.0 and 0.99 for finer control.
curl https://api.nucleus-ai.io/v1/chat/completions \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nucleus://run_3Bz:train:0/sampler_weights/000240",
"messages": [{ "role": "user", "content": "What is 17 × 23?" }],
"max_tokens": 64
}'{
"choices": [
{
"message": {
"role": "assistant",
"reasoning_content": "17 × 23 = 391",
"content": "391"
},
"finish_reason": "stop"
}
]
}