Integrate an OpenAI client with the Klu gateway

The Klu gateway is an OpenAI-compatible proxy. Point an OpenAI client at a gateway deployment and add Klu headers to log each provider request against an Action.

Choose the correct integration

The gateway and the Klu Action API serve different purposes:

• Use POST https://api.klu.ai/v1/actions/{guidOrSlug}/prompt when Klu should format and execute a deployed Action.
• Use a Klu gateway when your application already creates OpenAI-compatible messages and you want a proxy to forward and log those requests.
• Use POST /v1/actions/{guid}/gateway_payload only when you need Klu to prepare the provider payload before you forward it server-side.

Use the gateway base URL provided for your workspace. If you operate your own deployment, use its base URL.

Prerequisites

You need:

1. A provider API key, such as an OpenAI API key.
2. A Klu workspace API key.
3. A Klu Action GUID in the same workspace.
4. A gateway base URL that you operate or trust.

Keep both API keys on your server. A browser integration would expose the provider key and the Klu key.

Configure environment variables

export OPENAI_API_KEY='YOUR_OPENAI_API_KEY'
export KLU_API_KEY='YOUR_API_KEY'
export KLU_ACTION_GUID='YOUR_ACTION_GUID'
export KLU_GATEWAY_BASE_URL='YOUR_GATEWAY_BASE_URL'

KLU_ACTION_GUID is an identifier, so it usually does not need secret storage. It must still identify an Action available to the workspace API key or Klu cannot create the logged data point.

TypeScript

Install the official OpenAI client:

npm install openai

import OpenAI from 'openai'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.KLU_GATEWAY_BASE_URL,
  defaultHeaders: {
    'x-klu-api-key': process.env.KLU_API_KEY!,
    'x-klu-action-guid': process.env.KLU_ACTION_GUID!,
  },
})

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Write a one-sentence welcome message.' },
  ],
})

console.log(completion.choices[0]?.message.content)

Python

Install the official OpenAI client:

python -m pip install openai

import os

from openai import OpenAI

openai = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["KLU_GATEWAY_BASE_URL"],
    default_headers={
        "x-klu-api-key": os.environ["KLU_API_KEY"],
        "x-klu-action-guid": os.environ["KLU_ACTION_GUID"],
    },
)

completion = openai.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Write a one-sentence welcome message."}
    ],
)

print(completion.choices[0].message.content)

The provider key remains the Bearer credential used for the proxied model request. x-klu-api-key authenticates the later Klu data-log request, and x-klu-action-guid associates that data with the Action. Use these exact header names.

Expected result

Your client receives an OpenAI-compatible completion or stream from the provider, and the gateway records the interaction in Klu.

Verify the generation in the Action's data view before relying on it for evaluations or analytics.

Streaming

Use the OpenAI client's normal stream: true option. The gateway forwards the stream and records the completed interaction.

const stream = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a short greeting.' }],
  stream: true,
})

for await (const event of stream) {
  process.stdout.write(event.choices[0]?.delta.content ?? '')
}

If the client disconnects early or the provider stream is malformed, the logged output can be incomplete even when some tokens reached the client.

Prepare a deployed Action for forwarding

The Action API can format a deployed Action without executing it:

curl 'https://api.klu.ai/v1/actions/YOUR_ACTION_GUID/gateway_payload' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "input": {
      "question": "What is the capital of France?"
    }
  }'

The response includes the OpenAI-compatible payload and the headers required to forward it. Remove headers from the JSON body, then send the remaining payload to the gateway's /chat/completions route with those headers.

This response contains provider credential material. Generate and forward it only in trusted server code. Do not expose it to a browser, persist it, or print it in logs.

Troubleshooting

If a request fails, check the gateway URL, provider credentials, model support, and the x-klu-api-key and x-klu-action-guid headers. Provider errors are returned to your client. Check the Action's data view to confirm whether logging succeeded.

Operating your own gateway

Treat a gateway you operate as a separate service with its own availability, access control, logging, and upgrade responsibilities.