OpenAI SDK#

This works the same for Python and JavaScript, for the Responses and Chat Completions APIs, streaming included. The base URL for OpenAI is http://127.0.0.1:8787/openai/v1. You can also set it with OPENAI_BASE_URL.

The same SDK reaches other providers through Lockpin: http://127.0.0.1:8787/v1 for Meta, and http://127.0.0.1:8787/<name>/v1 for the other OpenAI-compatible providers. See Other tools and base URLs.

Connect#

Python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8787/openai/v1",
    # api_key defaults to OPENAI_API_KEY; on a team server, pass your lp_... key
    default_headers={
        "X-Lockpin-Task": "fix-login-bug",
        "X-Lockpin-Budget-Usd": "0.50",
    },
)
resp = client.responses.create(model="gpt-6.1-sol", input="Fix the login bug")

To name the task per call instead of per client:

client.responses.create(model="gpt-6.1-sol", input="...",
                        extra_headers={"X-Lockpin-Task": "summarise-logs"})

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:8787/openai/v1",
  // apiKey defaults to OPENAI_API_KEY; on a team server, pass your lp_... key
  defaultHeaders: { "X-Lockpin-Task": "fix-login-bug", "X-Lockpin-Budget-Usd": "0.50" },
});
// per call: client.responses.create({...}, { headers: { "X-Lockpin-Task": "summarise-logs" } })

curl

curl http://127.0.0.1:8787/openai/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Lockpin-Task: fix-login-bug" -H "X-Lockpin-Budget-Usd: 0.50" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-sol", "input": "Fix the login bug"}'

The two headers:

Header	What it does
`X-Lockpin-Task`	Names the task. Calls with the same name share one budget.
`X-Lockpin-Budget-Usd`	The task’s budget in USD. It can only lower the budget below `-default-budget`.

Lockpin removes every X-Lockpin-* header before the call goes to the provider. See Budgets and tasks for the other headers.

When the cap hits#

The SDK raises an error with status 402 and does not retry it. In Python it is openai.APIStatusError; in JavaScript it is OpenAI.APIError with status === 402. The response body has error.code == "budget_exceeded" and a lockpin object with the numbers. In Python, read it from the response: e.body holds only the inner error object.

import openai

try:
    resp = client.responses.create(model="gpt-6.1-sol", input=history)
except openai.APIStatusError as e:
    if e.status_code == 402:      # budget reached: wrap up with what you have
        print(e.response.json()["lockpin"])   # {'task': ..., 'spent_usd': ..., 'budget_usd': ...}
        return partial_result
    raise

A streaming call gets the 402 before the stream starts.
The call never reached the provider, so it cost nothing.
If the SDK’s max_retries is above zero, connection errors are retried, and each attempt is metered on its own.

Models#

A model with no price is refused with HTTP 400 unknown_model. lockpin providers -models lists the priced ones. To add one, see Prices.

Verify#

After one call, the meter shows it under the task you named. Non-streaming replies carry X-Lockpin-Cost-Usd, X-Lockpin-Spent-Usd and X-Lockpin-Remaining-Usd.