SDK quickstart: Python

The official OpenAI Python SDK, pointed at api.greenjoules.cloud/v1. Streaming, async, embeddings, tool use — all the OpenAI patterns work unchanged.

Install

pip install openai

Hello world

from openai import OpenAI

client = OpenAI(
    base_url="https://api.greenjoules.cloud/v1",
    api_key="jc_…",   # from portal.greenjoules.cloud
)

r = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "hi"}],
)
print(r.choices[0].message.content)

The joule footer

The X-Energy-Joules response header is the energy your call cost. Pull it off the response:

resp = client.chat.completions.with_raw_response.create(
    model="auto",
    messages=[{"role": "user", "content": "summarize this email..."}],
)
parsed = resp.parse()
print(parsed.choices[0].message.content)
print("joules:", resp.headers.get("x-energy-joules"))
print("routed to:", resp.headers.get("x-routed-to"))
print("tier:", resp.headers.get("x-tier"))

Streaming

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "tell me a short story"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Async

from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.greenjoules.cloud/v1",
    api_key="jc_…",
)

async def main():
    r = await client.chat.completions.create(
        model="auto",
        messages=[{"role": "user", "content": "hi"}],
    )
    print(r.choices[0].message.content)

import asyncio
asyncio.run(main())

Embeddings

r = client.embeddings.create(
    model="text-embedding-3-small",
    input=["the quick brown fox", "lorem ipsum"],
)
for d in r.data:
    print(d.embedding[:6], "...")

Tool use

tools = [{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather in a location",
    "parameters": {
      "type": "object",
      "properties": { "location": { "type": "string" } },
      "required": ["location"],
    },
  },
}]

r = client.chat.completions.create(
    model="auto",
    tools=tools,
    messages=[{"role": "user", "content": "What\'s the weather in Helsinki?"}],
)

if r.choices[0].message.tool_calls:
    call = r.choices[0].message.tool_calls[0]
    # call.function.name, call.function.arguments
    pass

Errors

from openai import RateLimitError, APIStatusError

try:
    r = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 402:
        # Insufficient balance — top up via portal
        ...
    elif e.status_code == 429:
        # Energy budget hit
        ...
    else:
        raise

Next

For the Object Store side via boto3, see Migrate from AWS S3. For the workload deploy side, see CLI reference.