Quick start

The CarbonForge endpoint is OpenAI-compatible: use the OpenAI SDK, LiteLLM, LangChain, or plain HTTP. Anthropic and Google clients will not work against it.

What you need

For the curl examples: any OS with curl (preinstalled on Linux and macOS; on Windows, use PowerShell 7+, WSL, or Git Bash). Shell examples use bash syntax; on native Windows adapt the quoting and use $env:CF_API_KEY instead of $CF_API_KEY.
For the Python examples: Python 3.9 or newer and the client of your choice (pip install openai, litellm, or langchain-openai). Any OpenAI-compatible client works the same way; only the base URL and key change.

1. Get your credentials

Your CarbonForge contact sends the API key separately.

BASE_URL   https://endpoint.carbonforge.ai/v1
API_KEY    <sent separately>
MODELS     cf-chat   cf-batch

2. Recommended client configuration

Two SDK defaults work against you on this endpoint; results are much more reliable with both adjusted before the first real request:

Prefer leaving the output uncapped. The model reasons before answering and the reasoning counts against max_tokens, so a capped request can spend part or all of its budget before the answer starts, returning HTTP 200 with truncated (sometimes empty) content and finish_reason: "length" rather than an error. If bounded output is a hard requirement, pairing the cap with {"enable_thinking": false} (see Reasoning) restores normal behaviour.
A client timeout of at least 600 seconds is preferable. Most SDKs default to 60 s, which aborts work the endpoint would have completed: in a representative run, 6.6% of requests took longer than 60 s (slowest: 221 s; nothing exceeded 300 s).

3. First request

These examples use cf-chat, the model for interactive traffic; bulk work belongs on cf-batch. The split is explained in Pick the right model below.

curl https://endpoint.carbonforge.ai/v1/chat/completions \
  -H "Authorization: Bearer $CF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"cf-chat","messages":[{"role":"user","content":"Hello"}]}'

The model reasons before answering. The reasoning comes back in a separate field and can be ignored:

resp.choices[0].message.reasoning_content   # the thinking
resp.choices[0].message.content             # the answer

4. Pick the right model

model	use it for
`cf-chat`	someone is waiting on the response
`cf-batch`	scheduled or bulk work, nobody waiting

Throughput is the same or better on cf-batch; it simply carries no latency guarantee, so a single request may take considerably longer when the system is busy. Routing work to the matching tier lets each be tuned independently and keeps a large batch job from slowing your interactive traffic.

GET /v1/models returns the authoritative list for your key.

Batch work is just concurrency

There is no separate batch API. cf-batch takes ordinary concurrent requests, so a batch is many requests in parallel. Start around 16 to 32 concurrent and ramp while watching your own latency. Do not exceed 400 concurrent requests on one key.

Images

Inline base64 in the message content, using the OpenAI content-array shape with a data URL. There is no file upload endpoint.

{"model": "cf-chat", "messages": [{"role": "user", "content": [
  {"type": "text", "text": "What color is this image? Answer with one word."},
  {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}
]}]}

Support

Reply to your CarbonForge contact for issues or key rotation. Include the id field from any failing response (for example chatcmpl-...); it lets us find the exact request.

Quick start

On this page