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

Headers

Request Body

‍

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
  }
}

The strategy feature allows you to optimize model selection for specific criteria when multiple providers offer the same model. By adding strategy tags to your model parameter, you can prioritize models based on price, latency, or token rate.

Available Strategies

Usage

Strategy tags are appended to the model name using the "@" separator. You can combine multiple strategies in any order:

Single Strategy Examples

Price:

{
  "model": "GPT 4o@price",
  "messages": [...]
}

Latency:

{
  "model": "GPT 4o@latency",
  "messages": [...]
}

Token Rate:

{
  "model": "GPT 4o@token_rate",
  "messages": [...]
}

‍

Multiple Strategy Examples

When using multiple strategies, they can be combined in any order:

Price & Latency:

{
  "model": "GPT 4o@price@latency",
  "messages": [...]
}

Token Rate & Price

{
  "model": "GPT 4o@token_rate@latency",
  "messages": [...]
}

Latanecy + Token Rate + Price

{
  "model": "GPT 4o@price@latency@token_rate",
  "messages": [...]
}

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

1. Log in to your CLōD dashboard at https://app.clod.io
2. Navigate to the API Keys tab
3. Click Generate Key
4. Give it a name (e.g., dev-key, n8n-workflow) and optionally assign it to a Project
5. 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:

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:

1. Go to the Projects tab in your dashboard
2. Click New Project
3. 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

‍

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

‍