Endpoints
All HTTP endpoints exposed by CanalAPI, their protocol family, and typical use.
CanalAPI exposes three compatible protocols under the same Base URL:
- OpenAI Chat Completions / Responses / multimodal (recommended; works for every model)
- Anthropic Messages (native Claude format)
- Google Gemini native (
v1beta/v1)
Unless noted otherwise, every endpoint is authenticated via Authorization: Bearer <API Key>. See Authentication.
OpenAI-compatible endpoints (/v1/*)
| Endpoint | Method | Purpose |
|---|---|---|
/v1/chat/completions | POST | Chat completion (streaming / non-streaming / tool calls / vision) |
/v1/responses | POST | OpenAI Responses API (compatible with clients like Cursor / Cline) |
/v1/embeddings | POST | Text embeddings (OpenAI / DeepSeek / Zhipu, etc.) |
/v1/images/generations | POST | Text-to-image |
/v1/images/edits | POST | Image edits (multipart) |
/v1/images/variations | POST | Image variations (multipart) |
/v1/audio/transcriptions | POST | Speech-to-text (Whisper, multipart, 25 MB max per file) |
/v1/audio/translations | POST | Speech-to-English translation |
/v1/audio/speech | POST | Text-to-speech (binary audio response) |
/v1/moderations | POST | Content moderation |
/v1/models | GET | List models available to your account (IP rate-limited; works unauthenticated for public-visible models) |
/v1/models/:model | GET | Single model metadata |
/v1/dashboard/billing/credit_grants | GET | OpenAI-compatible balance query (wallet + subscription grants) |
Minimal request
curl "$CANALAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $CANALAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role":"user","content":"hello"}]
}'Paste-and-run snippets in more languages: Examples.
Anthropic Messages (/v1/messages)
If your codebase already speaks the Anthropic Claude native protocol, just switch the Base URL:
| Endpoint | Method | Purpose |
|---|---|---|
/v1/messages | POST | Claude Messages native format (including streaming) |
/v1/messages/count_tokens | POST | Count tokens (not billed) |
curl "$CANALAPI_BASE_URL/messages" \
-H "Authorization: Bearer $CANALAPI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 256,
"messages": [{"role": "user", "content": "hello"}]
}'Anthropic-native clients only need their base_url pointed at https://api.canalapi.com.
Gemini native (/v1beta/*, /v1/*)
Compatible with the official Google Gemini SDK and REST calls:
| Endpoint | Method | Purpose |
|---|---|---|
/v1beta/models/:model:generateContent | POST | Single generation |
/v1beta/models/:model:streamGenerateContent | POST | Streaming generation (SSE) |
/v1beta/models/:model:countTokens | POST | Token counting |
/v1beta/models/:model:embedContent | POST | Embeddings |
/v1beta/models/:model:batchEmbedContents | POST | Batch embeddings |
/v1beta/models, /v1/models | GET | List Gemini models |
Authentication accepts any of:
Authorization: Bearer <API Key>x-goog-api-key: <API Key>- Query parameter
?key=<API Key>
Public metadata endpoints
No API Key required; IP-rate-limited (default 60 req/min):
| Endpoint | Purpose |
|---|---|
GET /v1/models | Models available to your account (without a Key, returns publicly visible models) |
GET /api/public/announcements | Platform announcements |
GET /api/fx/latest | Latest FX rates (USD → JPY / CNY / EUR) |
GET /api/status | Service health |
Which protocol should you use?
- New project — Use the OpenAI-compatible surface with the official OpenAI SDK; it covers the most models.
- Already on the Anthropic SDK — Use
/v1/messagesdirectly; no business code changes, onlybase_urland Key. - Already on the Google Gen AI SDK — Use
/v1beta/*; existing SDK config works as-is.
Using the same model name across protocols routes to the same upstream model; pricing, quotas, and rate limits are computed per account regardless of protocol.