zephyrcode 3.0.0

Official Python SDK for ZephyrCode — the AI coding agent platform

ZephyrCode Python SDK

Official Python SDK for ZephyrCode — the AI coding agent platform

---

Installation

pip install zephyrcode

Quickstart

1. Get an API key

Create one at zephyrcode.space-z.ai/apikey. Your key will look like:

zephyr-yourname-aBcD123eFgH456...

2. Stream a chat completion

from zephyrcode import ZephyrCode, ContentEvent, DoneEvent

client = ZephyrCode(api_key="zephyr-yourname-xxx")

for chunk in client.chat.stream(
    message="Build a React login form with Tailwind CSS",
    model="z-code-ultra",
    mode="code",
):
    if isinstance(chunk, ContentEvent):
        print(chunk.delta, end="", flush=True)
    elif isinstance(chunk, DoneEvent):
        print(f"\n\n✅ Done — tools used: {chunk.tools_used}")

3. Non-streaming response

response = client.chat.create(
    message="Explain async/await in Python",
    model="z-code-pro",
)
print(response.content)
print(f"Reasoning steps: {len(response.reasoning)}")
print(f"Tool calls: {len(response.tool_calls)}")

---

API Reference

ZephyrCode(api_key, base_url, timeout)

Main client.

Parameter	Type	Default	Description
api_key	str	required	Your zephyr-{username}-{secret} key
base_url	str	https://zephyrcode.space-z.ai	API base URL
timeout	int	60	Request timeout in seconds

---

client.chat.stream(...)

Stream a chat completion as Server-Sent Events.

Parameter	Type	Default	Description
message	str	—	A single user message
messages	list[Message]	—	Full conversation history (alternative to message)
model	str	"z-code-ultra"	Model: z-code-ultra, z-code-pro, z-code-local
mode	str	"code"	Mode: code, agentic, architect, debug, review, explain, website, mobile
thinking	bool	True	Enable extended chain-of-thought
project_context	dict	None	{language, framework, files}

Yields typed event objects:

Event	Description
MetaEvent	Stream start — model + mode info
PlanEvent	Task decomposition with steps
ReasoningEvent	Chain-of-thought chunk
ToolCallEvent	Agent invokes a tool
ToolResultEvent	Structured tool output
ContentEvent	Markdown content delta (.delta attribute)
DoneEvent	Terminal event with stats
ErrorEvent	Fatal error (raises StreamError)

---

client.chat.create(...)

Same parameters as .stream(), but returns a single ChatResponse with .content, .reasoning, .tool_calls, .plan.

---

client.tts.create(text, voice, speed, translate, target_language)

Text-to-speech synthesis.

audio = client.tts.create(
    text="Hello, welcome to ZephyrCode!",
    voice="rachel",
    speed=1.0,
)
audio.save("welcome.wav")

Parameter	Type	Default	Description
text	str	required	Text to synthesize (max 4000 chars)
voice	str	"rachel"	Voice ID (see voice catalog)
speed	float	1.0	Playback speed (0.5–2.0)
translate	bool	False	Translate text before synthesis
target_language	str	None	Target language (e.g. "Hindi", "Spanish")

Returns TTSResponse with .audio (bytes) and .save(path).

Popular voices: adam, rachel, antoni, bella, arnold, hindi-priya, hindi-arjun, sofia, carlos, mei, yuki.

---

client.apikeys — API Key Management

# List all keys
keys = client.apikeys.list()

# Create a new key
new_key = client.apikeys.create(
    name="Production",
    permissions="all",        # "all", "restricted", "readonly"
    expiration="60d",         # "1d", "3d", "7d", "21d", "60d", "never"
    credit=100.0,             # USD spending limit (0 = unlimited)
    project="My App",
)
print(f"Save this key (shown once): {new_key.key}")

# Revoke a key
client.apikeys.revoke("key_abc123")

# Delete a key
client.apikeys.delete("key_abc123")

---

client.projects — Project Management

# List projects
projects = client.projects.list()

# Create a project
project = client.projects.create(name="My App")
print(f"Created project: {project.id}")

# Delete a project
client.projects.delete(project.id)

---

client.models — Model Information

models = client.models.list()
for m in models:
    print(f"{m.id} — {m.label}: {m.description}")

---

Models

Model	ID	Best for
Z Code Ultra	z-code-ultra	Frontier reasoning, multi-file refactors
Z Code Pro	z-code-pro	Everyday coding, quick fixes
Z Code Local	z-code-local	On-device, privacy-first

Modes

Mode	Description
website	Website Builder
mobile	Mobile App Builder
code	Write, edit, refactor production code
agentic	Autonomous multi-step engineering
architect	Design systems, evaluate tradeoffs
debug	Root-cause failures and fixes
review	Review diffs for security & performance
explain	Explain code and concepts

---

Error Handling

from zephyrcode import (
    ZephyrCode,
    AuthenticationError,
    RateLimitError,
    APIError,
    StreamError,
)

client = ZephyrCode(api_key="zephyr-...")

try:
    response = client.chat.create("Build a counter")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except APIError as e:
    print(f"API error ({e.status_code}): {e}")
except StreamError as e:
    print(f"Stream error: {e}")

---

Multi-turn Conversations

from zephyrcode import ZephyrCode, Message

client = ZephyrCode(api_key="zephyr-...")

history = [
    Message(role="user", content="Create a Python function to reverse a string"),
    Message(role="assistant", content="def reverse(s): return s[::-1]"),
    Message(role="user", content="Now add type hints and a docstring"),
]

for chunk in client.chat.stream(messages=history, model="z-code-ultra"):
    if hasattr(chunk, "delta") and chunk.delta:
        print(chunk.delta, end="", flush=True)

---

Project Context

response = client.chat.create(
    message="Add a login form to the App.tsx",
    model="z-code-ultra",
    mode="code",
    project_context={
        "language": "TypeScript",
        "framework": "React",
        "files": ["src/App.tsx", "src/components/Login.tsx"],
    },
)

---

License

MIT © ZephyrCode Labs

Links

• Documentation: zephyrcode.space-z.ai/docs
• API Keys: zephyrcode.space-z.ai/apikey
• Support: [e-mail]