Using the OpenAI SDK

Point a stock OpenAI SDK at Zumik's /v1 surface with a one-line base-URL swap, and when to prefer this over a native Zumik SDK.

Zumik exposes an exact OpenAI-compatible surface at https://api.zumik.ai/v1. The fastest way onto the platform is no new dependency at all: keep your existing OpenAI client and change the base URL and the key. Your request and response handling, streaming, and tool calls all stay the same. This is the path the OpenAI migration guide walks through end to end.

The base-URL swap

The only line that changes is the base URL. Pass a Zumik alias (code.fast, auto.balanced, reasoning.best, ...) as the model; Zumik resolves it server-side to a pinned provider release and reports the resolved release on the response headers, so a vanilla OpenAI SDK ignores the extra signal cleanly.

export ZUMIK_API_KEY="zk_..."

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zumik.ai/v1",   # the only change
    api_key=os.environ["ZUMIK_API_KEY"],
)

resp = client.chat.completions.create(
    model="code.fast",                    # a Zumik alias
    messages=[{"role": "user", "content": "Explain a rolling deploy."}],
)
print(resp.choices[0].message.content)

The official openai-go SDK takes the base URL via option.WithBaseURL. Streaming, function/tool calling, and structured output behave exactly as they do against OpenAI - that is the compatibility contract: no proprietary fields in the request or response body.

Reuse stays measurable

Proprietary outcomes ride on response headers so the JSON body stays byte-for-byte OpenAI's shape. Send -i (or inspect the response headers in your SDK) to see them:

Agent-Execution-Profile: managed_provider
Agent-QoS-Target-Met: true
Agent-Trace-Id: trc_...

Where reuse savings apply, the discounted input fraction is also reflected in the standard usage.prompt_tokens_details.cached_tokens field, so reuse stays measurable with a stock OpenAI SDK and nothing proprietary in the body.

When to prefer this vs a native SDK

Prefer the OpenAI SDK swap

You have an existing OpenAI integration, you want streaming or the full chat/embeddings options today, or you just want generation against a Zumik alias with zero new dependencies.

Prefer a native Zumik SDK

You want explicit state - artifacts, bundles, sessions, branches, snapshots - plus diagnostics, token counts, and signed purge as first-class objects on /v2.

The two compose. A common shape is to build and pin state with a Zumik SDK on /v2, then run generation with the stock OpenAI client on /v1, attributing the request to the session with Agent-* headers. The coding-agent example does exactly this.

Tip

Keep stable content (system instructions, tools, schema) at the front of the request so provider prompt caching can match the prefix. The prompt linter checks the layout; prompt layout explains the ordering.