Getting Started

Welcome to CLōD. This guide covers everything you need to go from zero to your first API call, including how the model catalog works, how energy-based pricing keeps your costs low, and how to organize your usage with Projects.

‍

Step 1 Create Your Account

Go to https://app.clod.io and sign up for free. No credit card required.

Your free account gives you immediate access to:

30+ free LLMs
100 free requests per day (auto-replenished daily)
API key generation
The Studio playground
Activity logs

‍

Step 2 Get Your API Key

Log in to your CLōD dashboard at https://app.clod.io
Navigate to the API Keys tab
Click Generate Key
Give it a name (e.g., dev-key, n8n-workflow) and optionally assign it to a Project
Copy the key

The dashboard also displays the API endpoint alongside your key for quick reference.

Store your key as an environment variable never hardcode it:

export CLOD_API_KEY="your_clod_api_key"

Never expose your API key in client-side code, public repositories, or version-controlled config files.

‍

Step 3 Understand the Model Catalog

CLōD organizes all models into three categories. You can browse the full catalog at https://app.clod.io/auth/models.

‍

1. Free Models

Open-source models available at no cost. Identified by a Free label in the catalog.

Every account gets 100 free requests per day, automatically replenished at midnight
If you exhaust your daily free requests, you can top up your wallet to continue using free models at their standard per-token rate
Free credits do not apply to non-free models

‍

2. CLōD-Hosted Models

Models hosted directly on CLōD's GPU infrastructure across North America. This is where energy-based dynamic pricing applies (see Step 4 below). Many free models are also available under this category.

‍

3. Third-Party Models

Proprietary closed-source models (e.g., GPT-4o, Claude) that CLōD proxies through a unified endpoint. These are models CLōD cannot host directly.

The value here is simplicity: instead of managing separate API keys and billing accounts for each provider, you access all of them through a single CLōD API key. A 5% routing fee applies on top of the provider's standard rate.

‍

Step 4 How Energy Routing Works (and Why It Saves You Money)

This is CLōD's unique value proposition for hosted models.

CLōD operates GPU servers at multiple locations across North America. Electricity costs at each location fluctuate throughout the day based on real-time energy market prices. CLōD continuously monitors these costs and dynamically adjusts token pricing to always route your request to the lowest-cost available Data Center.

What this means for you:

You always pay the lowest available rate at the time of your request
No manual configuration required, routing is handled automatically
Pricing on hosted models can be up tp 60% lower than other places

‍

Viewing price history: In the Models page of your dashboard, each CLōD-hosted model displays a live pricing chart. You can toggle between 4-hour, 24-hour, and 7-day views to understand pricing trends. If your workload is flexible, scheduling high-volume jobs during low-energy-cost windows can reduce your inference spend materially.

For current token prices, always refer to the live model card in your dashboard , rates update in real time.

‍

Step 5 Make Your First API Call

CLōD's API is fully OpenAI-compatible. If you already use the OpenAI SDK, you only need to change the base_url and your API key.

Base URL: https://api.clod.io/v1

‍Endpoint: POST /v1/chat/completions

‍

cURL

curl -X POST "https://api.clod.io/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CLOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek V3",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 50
  }'

`‍`Python

curl -X POST "https://api.clod.io/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_CLOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek V3",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 50
  }'

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.clod.io/v1",
  apiKey: process.env.CLOD_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "DeepSeek V3",
  messages: [
    {
      role: "user",
      content: "Explain how electricity markets work in 3 sentences."
    }
  ],
});

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

`‍`Example Response

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.clod.io/v1",
  apiKey: process.env.CLOD_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "DeepSeek V3",
  messages: [
    {
      role: "user",
      content: "Explain how electricity markets work in 3 sentences."
    }
  ],
});

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

‍

Step 6 Organize with Projects

Projects let you group models, API keys, and logs into isolated environments. This is useful for separating teams, use cases, or deployment stages.

To create a project:

Go to the Projects tab in your dashboard
Click New Project
Assign models and API keys to the project

Project features:

Isolated activity logs. Requests are attributed to their project, making it easy to track usage per team or environment
Log encryption. Enable encryption in project settings so only holders of the private key can access request logs
Budget controls. Set daily and monthly spend caps per project. Once the cap is reached, the project stops processing requests for that period, preventing unexpected costs

‍

Dashboard Quick Reference

Section	What it does
Models	Browse the full catalog, view live pricing charts, check context window sizes
Projects	Create isolated environments with separate keys, logs, and budgets
API Keys	Generate and manage keys, scoped to projects
Studio	Browser-based playground to test any model before integrating
Activity	Monitor requests, token usage, latency, TTFT, and cost across your account

What to Do Next

Browse the full model catalog: https://app.clod.io/auth/models
Explore the Swagger API reference: https://newapp.clod.io/api#/
Set up an integration: OpenClaw, n8n, Kilo Code, Roo Code (see the Integrations section)
Join the community on Discord for support and updates

‍

Chat Completions API

The /v1/chat/completions API is designed to generate text-based responses from various language models. It's built for flexibility, allowing you to choose your model, adjust settings, and optimize for cost, speed, or token rate.

Request Structure

Property	Value
HTTP Method	POST
Base URL	https://api.clod.io
Endpoint	/v1/chat/completions

Headers

Parameter	Description
Authorization	Bearer (apikey) Your unique CLōD API key
Content-Type	application/json

Request Body

Parameter	Type	Description
model	string	Identifier of the model or strategy to use (e.g., "GPT 4o", "GPT 4o@price", "@latency").
messages	array	An array of message objects, each with role ("user", "assistant", "system") and content.
temperature	number	Optional. Sampling temperature (0-2). Higher values make output more random. Default varies by model.
max_completion_tokens	integer	Optional. Maximum number of tokens to generate. Default varies by model.
stream	boolean	Optional. If true, enables streaming of results. Default: false.
…	…	Other OpenAI-compatible parameters are supported.

‍

Example Request

JSON Example

{
  "model": "GPT 4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "temperature": 0.7,
  "max_completion_tokens": 50
}

CURL Example

curl -X POST "https://api.clod.io/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GPT 4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 50
  }'

Python Example

import requests
import json

url = "https://api.clod.io/v1/chat/completions"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "model": "GPT 4o",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 50
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(json.dumps(result, indent=2))

Example Response

{
  "id": "chatcmpl-xxxxxxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "GPT 4o", // Actual model used
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

OpenClaw Integration with CLōD

Integrate OpenClaw with CLōD to route your AI agent inference through CLōD’s OpenAI-compatible API endpoint.

This allows your OpenClaw agents to access multiple models through a single endpoint while using CLōD for unified model access and usage monitoring.

‍

What is OpenClaw?

OpenClaw is an open-source AI agent gateway that routes agent inference requests to configurable model providers.

By configuring CLōD as a provider, OpenClaw agents can send inference requests directly through the CLōD API.

‍

Setup

There are two ways to configure OpenClaw to use CLōD.

Recommended:
Use the OpenClaw onboarding wizard.

Advanced:
Manually configure the provider in the OpenClaw JSON configuration file.

‍

Recommended Setup (OpenClaw Onboard Wizard)

If you are setting up OpenClaw for the first time, the easiest method is using the built-in onboarding tool.

Run:

openclaw onboard

During onboarding select:

Provider: Custom Provider

Provider Name:

custom-api-clod-io

Base URL:

https://api.clod.io/v1

Note:
The /v1 suffix is required because CLōD uses an OpenAI-compatible API format.

You will also be prompted to enter your CLōD API key and configure your default model.

Once onboarding finishes, OpenClaw automatically creates the required configuration entries.

‍

Getting Your CLōD API Key

Before configuring OpenClaw you will need a CLōD API key.

Log in to the CLōD dashboard
Navigate to the API keys section
Generate a new API key

Dashboard:

https://app.clod.io

Copy the API key. You will use it in your OpenClaw configuration.

‍

Recommended Security Method (Environment Variable)

For better security, store your API key in an environment variable instead of placing it directly inside configuration files.

Example:

export CLOD_API_KEY="your_clod_api_key"

This keeps your API key out of version control and configuration files.

‍

Manual Configuration (Advanced)

Advanced users can configure CLōD directly in the OpenClaw configuration file.

Open:

~/.openclaw/openclaw.json

‍

Add the CLōD provider configuration.

Example:

{
  "models": {
    "mode": "merge",
    "providers": {
      "custom-api-clod-io": {
        "baseUrl": "https://api.clod.io/v1",
        "apiKey": "YOUR_CLOD_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "DeepSeek V3",
            "name": "DeepSeek V3 (CLŌD)",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

Replace:

YOUR_CLOD_API_KEY

with your actual CLōD API key.

‍

Using Environment Variables in JSON (Recommended)

Instead of placing the API key directly in the config file, you can reference the environment variable.

Example:

{
  "models": {
    "mode": "merge",
    "providers": {
      "custom-api-clod-io": {
        "baseUrl": "https://api.clod.io/v1",
        "apiKey": "$CLOD_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "DeepSeek V3",
            "name": "DeepSeek V3 (CLŌD)",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

Then define the key:

export CLOD_API_KEY="your_clod_api_key"

‍

Choosing a Model

CLōD supports multiple models that can be used through OpenClaw.

Model identifiers should match the names listed in the CLōD model catalog.

Model catalog:

https://app.clod.io/user/models

Examples of available models:

• DeepSeek V3
• Llama 3.1 8B
• Minimax M2.5

When configuring a model in OpenClaw, use the exact name provided in the CLōD model list.

Example:

"id": "Llama 3.1 8B"

‍

Context Window Configuration

The contextWindow parameter must match the maximum context supported by the model you are using.

Typical values include:

‍

Model	Context Window
DeepSeek V3	128000
Llama 3.1 8B	128000
Some extended models	up to 400000

If you configure a context window larger than what the model supports, inference requests may fail.

Always verify supported context sizes on the CLōD model page.

‍

Starting OpenClaw

After configuration is complete, start or restart the OpenClaw gateway.

Example:

openclaw gateway run

OpenClaw will load the custom-api-clod-io provider and route inference requests through CLōD.

‍

Monitoring Usage

Once OpenClaw is running with CLōD, you can monitor inference usage from the CLōD dashboard.

Dashboard:

https://app.clod.io

From the dashboard you can view:

• Request activity
• Token usage
• Model usage
• Total consumption

This helps track how your OpenClaw agents are using inference resources.

n8n Integration with CLōD

This is an n8n community node for the CLōD API, an OpenAI-compatible LLM service.

Installation

In your n8n instance, go to Settings > Community Nodes and install:

@clod_io/n8n-nodes-clod

‍

Or install via npm:

npm install @clod_io/n8n-nodes-clod

Credentials

Go to https://app.clod.io and sign in
Navigate to your account settings to get your API key
In n8n, create new credentials of type CLōD API and enter your API key

Usage

The CLōD node supports chat completions with the following parameters:

Model (required): The model name to use (e.g., "Llama 3.1 8B")
Messages (required): JSON array of message objects with role and content
Options:
- Temperature (0-2)
- Max Tokens
- Stream

Example Messages Format

[
  {"role": "system", "content": "You are a helpful assistant."},
  {"role": "user", "content": "Hello!"}
]

‍

License

MIT

‍

Kilo Code Integration with CLōD

Use the Kilo Code VS Code extension with CLōD by connecting it to CLōD’s OpenAI-compatible API endpoint.

This allows Kilo Code to route inference requests through CLōD and access any model available in your CLōD account.

‍

What is Kilo Code?

Kilo Code is a VS Code extension for agentic coding, allowing AI models to read files, run commands, and assist with development workflows inside your code editor.

By connecting Kilo Code to CLōD, you can use CLōD-hosted models directly inside VS Code.

‍

Setup

Follow these steps to connect Kilo Code to CLōD.

‍

Step 1 Install the Kilo Code Extension

Open VS Code
Open the Extensions panel

Ctrl + Shift + X

Search for Kilo Code
Click Install

‍

‍Step 2 Configure CLōD as an OpenAI-Compatible Provider

Open the Kilo Code settings and configure the provider.

Set the following values:

Provider:
OpenAI Compatible

Base URL:

https://api.clod.io/v1

Note:
The /v1 suffix is required because CLōD uses an OpenAI-compatible API format.

API Key
Enter your CLōD API key.

If you do not have an API key yet, create one in the CLōD dashboard.

https://app.clod.io

‍

Step 3 Select a Model

Once the API key is entered, Kilo Code will automatically fetch the models available in your CLōD account.

You can then select a model directly from the Kilo Code interface.

Examples of available models include:

• DeepSeek V3
• Llama 3.1 8B
• Minimax M2.5

The available models depend on what is enabled in your CLōD account.

‍

Model Requirements

Kilo Code performs agentic actions such as:

• reading files
• running commands
• editing code

These capabilities rely on tool calling (function calling).

For best results, choose a model that supports tool usage.

You can view available models in the CLōD model catalog:

https://app.clod.io/user/models

‍

Try It

Once configured, you can start using Kilo Code with CLōD.

Examples of useful prompts:

Scan this repository and explain the architecture in 10 bullets.

Find the entry point for feature X and show the call chain.

Run tests and fix the first failing test.

Refactor module X and update all related imports.

‍

Monitoring Usage

You can monitor inference usage from the CLōD dashboard.

https://app.clod.io

From the dashboard you can view:

• Request activity
• Token usage
• Model usage
• Overall consumption

Next Steps

Once connected to CLōD, you can:

• Switch between available models
• Use larger-context models when needed
• Monitor inference usage through the CLōD dashboard
• Integrate CLōD into additional developer tools

Using CLōD with the OpenAI SDK

Frameworks and Integrations

CLōD provides an OpenAI-compatible API, which means most tools and frameworks that support the OpenAI API can connect to CLōD with minimal configuration.

This includes:

• OpenAI SDK
• LangChain
• LiteLLM
• AI coding assistants
• agent frameworks
• custom applications

To connect to CLōD, configure the API endpoint and your API key.

Quick API Example

You can verify your CLōD connection by sending a simple request to the API.

cURL Example

curl https://api.clod.io/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer YOUR_CLOD_API_KEY" \
 -d '{
   "model": "DeepSeek V3",
   "messages": [
     {
       "role": "user",
       "content": "What is the meaning of life?"
     }
   ]
 }'

‍

If successful, the API will return a response containing the model’s output.

Install the OpenAI SDK

You can use the official OpenAI SDK with CLōD.

Python

pip install openai

Node.js

npm install openai

Python Example

from openai import OpenAI

client = OpenAI(
   base_url="https://api.clod.io/v1",
   api_key="YOUR_CLOD_API_KEY",
)

completion = client.chat.completions.create(
   model="DeepSeek V3",
   messages=[
       {
           "role": "user",
           "content": "Explain how electricity markets work in 3 sentences."
       }
   ]
)

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

Node.js Example

import OpenAI from "openai";

const client = new OpenAI({
 baseURL: "https://api.clod.io/v1",
 apiKey: process.env.CLOD_API_KEY,
});

const completion = await client.chat.completions.create({
 model: "DeepSeek V3",
 messages: [
   {
     role: "user",
     content: "Explain how electricity markets work in 3 sentences."
   }
 ],
});

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

Roo Code Integration with CLōD

Use the Roo Code VS Code extension with CLōD by connecting it to CLōD’s OpenAI-compatible API endpoint.

This allows Roo Code to route inference requests through CLōD and access any model available in your CLōD account.

What is Roo Code?

Roo Code is a VS Code extension for agentic coding, allowing AI models to analyze projects, generate code, refactor files, and assist with development workflows inside your editor.

By connecting Roo Code to CLōD, you can use CLōD-hosted models directly within VS Code.

Setup

Follow these steps to connect Roo Code to CLōD.

Step 1 Install Roo Code

Open VS Code
Open the Extensions panel

Ctrl + Shift + X

Search for Roo Code
Click Install

Step 2 Configure CLōD as an OpenAI-Compatible Provider

Open the Roo Code settings and configure the provider.

Set the following values:

Provider
OpenAI Compatible

Base URL

https://api.clod.io/v1

Note:
The /v1 suffix is required because CLōD uses an OpenAI-compatible API format.

API Key
Enter your CLōD API key.

If you do not have an API key yet, generate one from the CLōD dashboard.

https://app.clod.io

Step 3 Select a Model

After entering your API key, Roo Code will automatically fetch the models available in your CLōD account.

You can then select a model directly from the Roo Code interface.

Examples of available models include:

• DeepSeek V3
• Llama 3.1 8B
• Minimax M2.5

The models shown depend on what is enabled in your CLōD account.

Model Requirements

Roo Code performs agentic actions, including:

• reading project files
• running commands
• modifying code
• refactoring modules

These capabilities rely on tool calling (function calling).

For best results, choose a model that supports tool usage.

You can view available models in the CLōD model catalog:

https://app.clod.io/user/models

Try It

Once configured, you can start using Roo Code with CLōD inside VS Code.

Example prompts:

Map the main modules in this repository and explain their purpose.

Find where request X is handled and describe the execution flow.

Refactor this logic into a helper function and update all call sites.

Run lint or tests and fix issues until the build passes.

Monitoring Usage

You can monitor inference usage from the CLōD dashboard.

https://app.clod.io

From the dashboard you can view:

• request activity
• token usage
• model usage
• overall consumption

Next Steps

Once Roo Code is connected to CLōD, you can:

• switch between models available on CLōD
• use higher-context models when working with large repositories
• monitor inference usage through the CLōD dashboard
• integrate CLōD with additional development tools

Getting Started

Step 1 Create Your Account

Step 2 Get Your API Key

Step 3 Understand the Model Catalog

1. Free Models

2. CLōD-Hosted Models

3. Third-Party Models

Step 4 How Energy Routing Works (and Why It Saves You Money)

Step 5 Make Your First API Call

cURL

‍Python

Node.js

‍Example Response

Step 6 Organize with Projects

Dashboard Quick Reference

What to Do Next

Chat Completions API

Request Structure

Headers

Request Body

Example Request

JSON Example

CURL Example

Python Example

Example Response

OpenClaw Integration with CLōD

What is OpenClaw?

Setup

Recommended Setup (OpenClaw Onboard Wizard)

Getting Your CLōD API Key

Recommended Security Method (Environment Variable)

Manual Configuration (Advanced)

Using Environment Variables in JSON (Recommended)

Choosing a Model

Context Window Configuration

Starting OpenClaw

Monitoring Usage

n8n Integration with CLōD

Installation

Credentials

Usage

Example Messages Format

License

Kilo Code Integration with CLōD

What is Kilo Code?

Setup

Step 1 Install the Kilo Code Extension

Step 3 Select a Model

Model Requirements

Try It

Monitoring Usage

Next Steps

Using CLōD with the OpenAI SDK

Frameworks and Integrations

Quick API Example

cURL Example

Install the OpenAI SDK

Python

Node.js

Python Example

Node.js Example

Roo Code Integration with CLōD

What is Roo Code?

Setup

Step 1 Install Roo Code

Step 2 Configure CLōD as an OpenAI-Compatible Provider

Step 3 Select a Model

Model Requirements

Try It

Monitoring Usage

Next Steps

`‍`Python

`‍`Example Response