API Quickstart
Use these examples to connect your app or script. For Claude Code, Codex and other coding tools, follow the tool setup guides.
- Top up your wallet and create an API key.
- Choose a model from the catalog that supports the endpoint below.
- Set
CODEBYAI_API_KEYas shown below, replaceMODEL_IDwith your chosen model, then run the request. Successful requests use your balance; never share the key.
Messages supports Claude. Responses supports GPT, Codex and Claude; Chat Completions also supports Grok. Gemini models use the Gemini endpoint. Unknown IDs return HTTP 400. Only the JSON model field on Messages, Responses and Chat Completions can be omitted to use a default; the Gemini URL always requires a model ID.
Set up your terminal
Use curl 7.76+, Python 3.10+ or Node.js 20+. These examples need no SDK packages. Replace YOUR_API_KEY in the setup command with your key; keep the name CODEBYAI_API_KEY unchanged. Run it in the terminal you will use for the request. Opening a new terminal requires setting it again.
macOS / Linux (bash / zsh):
1 export CODEBYAI_API_KEY="YOUR_API_KEY"
Windows PowerShell, for the Python and JavaScript examples:
1 $env:CODEBYAI_API_KEY="YOUR_API_KEY"
Run the generated example
Open the homepage generator, choose the protocol, model and language, then copy the example. Save scripts as plain text. Run them from their folder in the same terminal where you set the key.
| Language | Save as | Run |
|---|---|---|
| curl | Not required | Paste into bash / zsh |
| Python | request.py | python3 request.py |
| JavaScript | request.mjs | node request.mjs |
On Windows, use python request.py for Python; the Node.js command is the same. The curl examples use bash / zsh syntax, so on Windows use Git Bash or WSL. Do not paste Python or JavaScript source directly into the shell. The curl examples below use the same environment variable.
If you see Set CODEBYAI_API_KEY, set the key again in the same terminal and retry. An HTTP error prints its status and error body; check the cause before rerunning the request.
Anthropic Messages
1 curl --fail-with-body --max-time 120 https://www.codebyai.net/api/agent/v1/messages \2 -H "x-api-key: ${CODEBYAI_API_KEY:?Set CODEBYAI_API_KEY}" \3 -H "anthropic-version: 2023-06-01" \4 -H "content-type: application/json" \5 -d '{"model":"MODEL_ID","max_tokens":256,"messages":[{"role":"user","content":"Hello"}]}'
Claude models only. x-api-key is the header this endpoint reads first. anthropic-version is forwarded to the Claude channel.
OpenAI Responses
1 curl --fail-with-body --max-time 120 https://www.codebyai.net/api/agent/v1/responses \2 -H "Authorization: Bearer ${CODEBYAI_API_KEY:?Set CODEBYAI_API_KEY}" \3 -H "content-type: application/json" \4 -d '{"model":"MODEL_ID","input":"Hello"}'
GPT and Codex models, and also claude-* models, which are forwarded to the Claude channel and billed at Claude prices.
OpenAI Chat Completions
1 curl --fail-with-body --max-time 120 https://www.codebyai.net/api/agent/v1/chat/completions \2 -H "Authorization: Bearer ${CODEBYAI_API_KEY:?Set CODEBYAI_API_KEY}" \3 -H "content-type: application/json" \4 -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"Hello"}]}'
Chat Completions supports GPT, Codex, Claude and Grok. Responses does not support Grok. Point an OpenAI SDK's base URL at https://www.codebyai.net/api/agent/v1 or https://www.codebyai.net/api/agent.
Gemini
1 curl --fail-with-body --max-time 120 "https://www.codebyai.net/api/agent/v1beta/models/MODEL_ID:generateContent" \2 -H "x-goog-api-key: ${CODEBYAI_API_KEY:?Set CODEBYAI_API_KEY}" \3 -H "content-type: application/json" \4 -d '{"contents":[{"role":"user","parts":[{"text":"Hello"}]}]}'
Gemini models only. The key header is x-goog-api-key.
Check the response
A successful request returns HTTP 200. Find the generated text and token usage in these fields; the exact response varies by model.
| Protocol | Generated text | Token usage |
|---|---|---|
| Messages | content[].text | usage |
| Responses | output[].content[].text | usage |
| Chat Completions | choices[].message.content | usage |
| Gemini | candidates[].content.parts[].text | usageMetadata |
If you receive 400, check the model ID and endpoint. For authentication or balance errors, see common errors.