Build with Echo

Send an Echo API key as a bearer token on every request. Create a key from the API keys page; the complete secret is shown only once.

Authorization: Bearer ECHO_API_KEY

These examples call the same text completion endpoint. SDK examples disable automatic retries so your application can handle failures and idempotency intentionally.

curl --fail-with-body --silent --show-error \
  https://echo.tracerml.ai/v1/chat/completions \
  -H "Authorization: Bearer ${ECHO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "echo",
    "messages": [
      {"role": "user", "content": "Explain recursion in one sentence."}
    ],
    "max_tokens": 128
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ECHO_API_KEY"],
    base_url="https://echo.tracerml.ai/v1",
    timeout=600.0,
    max_retries=0,
)

completion = client.chat.completions.create(
    model="echo",
    messages=[
        {"role": "user", "content": "Explain recursion in one sentence."}
    ],
    max_tokens=128,
)

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

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ECHO_API_KEY,
  baseURL: "https://echo.tracerml.ai/v1",
  timeout: 600_000,
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: "echo",
  messages: [
    { role: "user", content: "Explain recursion in one sentence." },
  ],
  max_tokens: 128,
});

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

Supply Echo as the model endpoint inside a user-run harness. Your harness owns the repository, shell, files, browser, and tool execution while Echo supplies the intelligence through one OpenAI-compatible endpoint. Every direct integration uses API base https://echo.tracerml.ai/v1, public wire model echo, and a secret supplied through ECHO_API_KEY.

OpenCode: recommended setup

OpenCode selects echo/echo locally, while the HTTP model remains exactly echo. Back up the active opencode.json, preserve unrelated settings, and merge this block.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "echo/echo",
  "provider": {
    "echo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Echo",
      "options": {
        "baseURL": "https://echo.tracerml.ai/v1",
        "apiKey": "{env:ECHO_API_KEY}"
      },
      "models": {"echo": {"name": "Echo"}}
    }
  }
}

Supply the real key through the user's secret manager. The value below is a placeholder. Confirm the config resolves the harness-local selector.

export ECHO_API_KEY='<your-echo-api-key>'
opencode models echo

Verify the standard Chat Completions streaming path with this API smoke test.

curl --fail-with-body --no-buffer \
  https://echo.tracerml.ai/v1/chat/completions \
  -H "Authorization: Bearer ${ECHO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "echo",
    "messages": [{"role": "user", "content": "Reply with one short sentence."}],
    "stream": true,
    "stream_options": {"include_usage": true},
    "parallel_tool_calls": false
  }'

Copy to your coding agent

Configure this OpenCode installation to use Echo as its model endpoint. Back up the active `opencode.json`, then merge a custom `@ai-sdk/openai-compatible` provider named `echo` with `baseURL` `https://echo.tracerml.ai/v1`, `apiKey` `{env:ECHO_API_KEY}`, model map `echo`, and selector `echo/echo`, without deleting unrelated settings. Keep the credential only in `ECHO_API_KEY` and never read, print, log, or write its value. Confirm `opencode models echo` resolves `echo/echo` and that HTTP requests send model `echo` to `/v1/chat/completions`. Preserve native function tools, assistant tool calls, matching tool results, and complete conversation history across turns. Use `parallel_tool_calls=false`. Then run this task in a disposable repository: "Inspect this scratch repository, implement one small multi-file feature using native file and shell tools, run the repository's tests, repair any failure, and report the files changed and test results. Never read or print environment variables or secrets." OpenCode executes the tools; Echo is the model endpoint. If a request fails, report its HTTP status, public error code, and `X-Tracer-Request-ID`; do not switch model IDs.

Use the configuration matching your harness below. In every case, keep the API key in the environment and send the public model ID echo.

Harness releases may rename configuration fields, so confirm them against the linked version documentation. For Responses integrations, resend the complete transcript on every turn and omit previous_response_id. Claude Code uses an Anthropic-compatible adapter rather than the direct OpenAI-compatible endpoint.

Use this stateless Responses smoke test for Continue, Hermes Agent, OpenClaw, LangChain/LangGraph, PydanticAI, and Codex CLI. The input array is the complete request history, store is false, and previous_response_id is deliberately absent.

curl --fail-with-body --silent --show-error \
  https://echo.tracerml.ai/v1/responses \
  -H "Authorization: Bearer ${ECHO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "echo",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Call echo_fixture exactly once."}
        ]
      }
    ],
    "store": false,
    "tools": [
      {
        "type": "function",
        "name": "echo_fixture",
        "description": "Return a fixed local fixture.",
        "parameters": {
          "type": "object",
          "properties": {},
          "additionalProperties": false
        },
        "strict": false
      }
    ],
    "tool_choice": {"type": "function", "name": "echo_fixture"},
    "parallel_tool_calls": false,
    "stream": false
  }'

Use one model ID and one endpoint. Echo automatically assigns the intelligence level required by each request; you do not select a mode.

Current alpha rate card, effective July 15, 2026. Prices are in USD per one million metered tokens.

Send a JSON object with a non-empty message history containing at least one user message. Conversations are stateless; include the history needed for each request.

A successful non-streaming request returns one assistant message. Read a text answer from choices[0].message.content. A function request instead returns message.tool_calls and finish_reason: "tool_calls". Retain the X-Tracer-Request-ID response header for support.

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1780000000,
  "model": "echo",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Recursion solves a problem by reducing it to smaller instances of itself."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 14,
    "total_tokens": 32
  }
}

Usage and cost fields

The standard usage object reports prompt, completion, and total tokens. It does not include a cost field, and token counts should not be treated as an invoice calculation.

For raw streaming clients, the optional X-Tracer-Progress: 1 header can add a tracer.usage event after a successful completion. Its usage payload may include:

Cost events are optional. Use the account dashboard as the source for usage and billing records.

Set stream: true. Echo responds with text/event-stream; append content deltas or accumulate indexed delta.tool_calls fields in order, then stop when you receive data: [DONE].

X-Tracer-Stream-Mode is native for screened provider deltas and buffered when generation or full-response screening completed before presentation chunks were released. Buffered responses can include a non-sensitive X-Tracer-Stream-Fallback reason. Parse both modes identically.

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"echo","choices":[{"index":0,"delta":{"role":"assistant","content":"One"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","model":"echo","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Application errors normally use an OpenAI-shaped error envelope. Framework validation failures, including malformed JSON or a missing body, may use a different 422 response shape.

{
  "error": {
    "message": "messages must be a non-empty array",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "invalid_request"
  }
}

Echo enforces request-rate limits and may apply account-specific concurrency and daily request limits. Limits are attributed to the tenant associated with the API key and can vary by deployment or account.

• On 429, honor the Retry-After response header when present.
• Otherwise use exponential backoff with jitter and a bounded retry count.
• Do not retry validation, authentication, billing, or policy failures unchanged.
• Monitor status, latency, interrupted streams, and X-Tracer-Request-ID.