Quickstart

Use the OpenAI SDK:

We default to max thinking (reasoning effort) and recommend it for best results. Use reasoning_effort="max", stream=true, and default sampling settings.

export PAPERINSTRUMENTS_API_KEY="pi_live_..."

pip install -U openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.paperinstruments.com/v1",
    api_key=os.environ["PAPERINSTRUMENTS_API_KEY"],
)

stream = client.chat.completions.create(
    model="ultramarine-1-flash",
    messages=[{"role": "user", "content": "Explain EBITDA in two sentences."}],
    reasoning_effort="max",
    max_completion_tokens=8192,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

Sticky routing and caching

The x-session-id header is optional. You can use it if you want sticky routing. When using it, reuse the same conversation ID across turns, retries, and tool results, and use a different ID for each conversation. Cache hits depend on matching prompt prefixes and cache availability.

See the header examples for Chat Completions, Responses, and Messages.

Prompting and packages

Ultramarine was trained with large-scale non-verifiable rewards, so it has more expressive aesthetic and prose-writing sensibilities than traditional models. It is critical to tune your prompts carefully to get the most out of it.

Feather Harness has examples of prompts we've tuned for internal testing. Start with its system prompts, profiles, and skills. For Word, PowerPoint, and Excel work, give the model the Paper packages. See Prompting and packages for details.

Next steps