Documentation / Getting started

Connect your app to Clydex.

Connect with Responses, configure your client, and add tools that run in your app.

Before you start

Create and copy a key in API Keys. Keep it private.
Choose an available model in Channels & Models. Use its exact ID in place of <MODEL_ID> below.
Open a guide below. Replace <YOUR_CLYDEX_API_KEY> with your key and save the files.

Clydex base URL

https://clydex.shop/v1

Want the settings filled in for you? Click Use Key on your key card, choose your app, and copy or download its configuration.

Choose your application

Codex CLI / App

Connect Codex with two files.

Open ~/.codex in your file manager. Create the folder if it is missing.
Save the settings as config.toml. Put the top-level settings before any [section] headings; keep your other settings.
Save auth.json in the same folder, then restart Codex or your editor and start a new chat.

~/.codex/config.toml

model_provider = "clydex"
model = "<MODEL_ID>"
disable_response_storage = true
cli_auth_credentials_store = "file"
web_search = "disabled"

[model_providers.clydex]
name = "Clydex"
base_url = "https://clydex.shop/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false
request_max_retries = 0
stream_max_retries = 0

~/.codex/auth.json

{
  "OPENAI_API_KEY": "<YOUR_CLYDEX_API_KEY>"
}

Back up an existing auth.json before replacing it. These settings also apply to the Codex IDE extension.

OpenCode

One config file, then choose Clydex in OpenCode.

Open ~/.config/opencode and create opencode.json if it does not exist.
Paste this configuration. If you already have a config, merge the Clydex provider and model settings into it.
Restart OpenCode. Run /models and select the model under Clydex.

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "clydex/<MODEL_ID>",
  "small_model": "clydex/<MODEL_ID>",
  "provider": {
    "clydex": {
      "npm": "@ai-sdk/openai",
      "name": "Clydex",
      "options": {
        "baseURL": "https://clydex.shop/v1",
        "apiKey": "<YOUR_CLYDEX_API_KEY>"
      },
      "models": {
        "<MODEL_ID>": {
          "name": "<MODEL_ID>",
          "options": {
            "store": false
          }
        }
      }
    }
  }
}

Hermes

Connect Hermes from your terminal.

Open ~/.hermes/config.yaml. Create the folder and file if needed.
Replace the model section with these settings; keep the rest of your configuration.
Save the file, restart Hermes, and begin a new conversation.

~/.hermes/config.yaml

model:
  provider: custom
  default: "<MODEL_ID>"
  base_url: "https://clydex.shop/v1"
  api_mode: codex_responses
  api_key: "<YOUR_CLYDEX_API_KEY>"

Cherry Studio

Add Clydex in Cherry Studio settings.

Open Settings → Model Providers and add a provider named Clydex.
Choose OpenAI Responses as the endpoint type. Paste the API address and key below.
Add the model ID <MODEL_ID>, enable the provider, and select that model in a new chat.

API address

https://clydex.shop/v1/

API key

<YOUR_CLYDEX_API_KEY>

Model ID

<MODEL_ID>

Keep web search and attachments off. In older versions, the provider type is called OpenAI-Response.

API / SDKs

Use your Clydex key with the OpenAI SDK Responses API.

Choose Python, JavaScript, or the terminal example below.
For Python, run pip install openai, then python hello.py. For JavaScript, run npm install openai, then node hello.mjs.

Base URL

https://clydex.shop/v1

hello.py

from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_CLYDEX_API_KEY>",
    base_url="https://clydex.shop/v1",
    max_retries=0,
)

response = client.responses.create(
    model="<MODEL_ID>",
    input="Say hello in one sentence.",
    max_output_tokens=128,
    store=False,
)
print(response.output_text)

hello.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<YOUR_CLYDEX_API_KEY>",
  baseURL: "https://clydex.shop/v1",
  maxRetries: 0,
});

const response = await client.responses.create({
  model: "<MODEL_ID>",
  input: "Say hello in one sentence.",
  max_output_tokens: 128,
  store: false,
});
console.log(response.output_text);

Terminal

curl 'https://clydex.shop/v1/responses' \
  -H 'Authorization: Bearer <YOUR_CLYDEX_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "<MODEL_ID>",
  "input": "Say hello in one sentence.",
  "max_output_tokens": 128,
  "store": false
}'

Keep files containing your key private. Run SDK examples on your computer or server, never in public browser code.

Function tools

Declare functions in tools. The model returns a call, your application executes it, and you send back a function_call_output with the same call_id. The example below shows a complete round trip.

Python example: use a local function

Using the client from hello.py above, replace its request with this example. It makes up to two model requests and runs a local clock function.

Function call and result

import json
import uuid
from datetime import datetime, timezone

history = [{"role": "user", "content": "What time is it in UTC?"}]
tools = [{
    "type": "function",
    "name": "get_utc_time",
    "description": "Return the current UTC time.",
    "parameters": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": False,
    },
    "strict": True,
}]

first = client.responses.create(
    model="<MODEL_ID>", input=history, tools=tools,
    tool_choice={"type": "function", "name": "get_utc_time"},
    parallel_tool_calls=False,
    include=["reasoning.encrypted_content"],
    max_output_tokens=256, store=False,
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)
history.extend(item.model_dump(exclude_none=True) for item in first.output)
calls = [item for item in first.output if item.type == "function_call"]
if len(calls) != 1 or calls[0].name != "get_utc_time":
    raise RuntimeError("Expected one get_utc_time call; check the response.")
call = calls[0]
if json.loads(call.arguments) != {}:
    raise RuntimeError("Unexpected function arguments.")
history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps({"utc": datetime.now(timezone.utc).isoformat()}),
})
final = client.responses.create(
    model="<MODEL_ID>", input=history, tools=tools, tool_choice="none",
    include=["reasoning.encrypted_content"],
    max_output_tokens=256, store=False,
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)
print(final.output_text)

Preserve the returned output items, including reasoning items, when building the next turn. Validate tool names and arguments in your application before executing a function. Custom tools use custom_tool_call and custom_tool_call_output with the same call/result pattern.

More help

Streaming and request options

Set stream: true for Responses streaming over HTTP. Tool call arguments can arrive in several events; assemble the complete call before executing it. Final usage arrives in the terminal response event. WebSocket transport is unavailable.

Set max_output_tokens for your requested output length. It is not a guaranteed spending cap. Reasoning options, text verbosity, and structured text formats are accepted where the selected model supports them. Keep storage off and send complete conversation history on each turn.

A request did not work

Check that the key is active and its balance has credit.
Use an available model ID and the correct endpoint for that model.
For an unsupported-field error, remove the option named in the error. If your app always sends it, use the API example.
After a timeout, check request history before trying again.

Find your usage and charges

Open request history to see request status, tokens, and cost. Pending requests are still being checked. See Statistics for totals, or Models & Pricing for rates.