OPENCAPLY · DEVELOPERS

Developer quickstart

Connect any OpenAI-compatible client in three steps

Quick Start

1

Copy the API Base URL

All requests go to this address; works with OpenAI SDKs and clients:

https://api.opencaply.com/v1

Note: the gateway address adapts to the current site automatically; production uses api.opencaply.com

2

Get an API Key

Keys start with sk- and are stored hashed only; the plaintext is shown once, so keep it safe:

3

Configure your client

In any OpenAI-compatible tool, choose “OpenAI Compatible”, then paste the URL and Key:

Cline / Roo CodeContinueCherry StudioChatBoxcurl

API Endpoints

POST/v1/chat/completionsCore

Chat completions with streaming (stream: true, SSE) and non-streaming modes. Supports temperature / top_p / max_tokens / stop / tools / response_format; unknown fields pass through to the upstream.

http
POST https://api.opencaply.com/v1/chat/completions
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "DeepSeek V4 Flash",
  "messages": [{ "role": "user", "content": "Hi" }],
  "stream": false
}

Streaming responses end with data: [DONE]; request body limit is 10MB (multimodal images included).

POST/v1/completionsLegacy

Legacy completions endpoint (text_completion format), internally converted to a chat request — for existing code.

Params: model / prompt / max_tokens / temperature / top_p / stream / stop.

GET/v1/modelsList

Lists all available public models (requires a valid API Key). Always use model names from this list.

bash
curl https://api.opencaply.com/v1/models \
  -H "Authorization: Bearer sk-xxx"
POST/v1/images/generationsImage

Generate images from text (native Gemini image models). Body: model, prompt, n, size; response: data[].b64_json.

http
POST https://api.opencaply.com/v1/images/generations
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "Gemini 3.1 Flash Image",
  "prompt": "A red circle on a white background",
  "size": "1024x1024",
  "n": 1
}

Billed per image; the mapping capability must be image. Size and unit prices are configurable in generation prices.

POST/v1/videosVideo

Create an asynchronous video job (Gemini Veo). Returns a job id and queued status.

http
POST https://api.opencaply.com/v1/videos
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "Veo 3.1 Fast",
  "prompt": "A red circle moving slowly",
  "seconds": 4
}

Poll GET /v1/videos/; when status is completed, download with GET /v1/videos//content. Billed per second and settled on completion.

GET/v1/videos/{id}Video

Check a video job status and get its download URL.

bash
GET https://api.opencaply.com/v1/videos/{id}
Authorization: Bearer sk-xxx

Client Configuration Examples

Cline / Roo Code
API Provider:  OpenAI Compatible
Base URL:      https://api.opencaply.com/v1
API Key:       sk-xxx
Model:         DeepSeek V4 Flash (see /v1/models)
Continue
{
  "models": [{
    "title": "OpenCaply",
    "provider": "openai",
    "model": "DeepSeek V4 Flash",
    "apiBase": "https://api.opencaply.com/v1",
    "apiKey": "sk-xxx"
  }]
}
curl
curl https://api.opencaply.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"DeepSeek V4 Flash","messages":[{"role":"user","content":"hi"}],"stream":false}'
curl · stream
curl -N https://api.opencaply.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"DeepSeek V4 Flash","messages":[{"role":"user","content":"hi"}],"stream":true}'

API Key Security

The Key plaintext is shown only once at creation; the server stores a hash only. Never share it with anyone.

Use a dedicated Key per application to track usage per Key on the dashboard.

Store Keys in server-side env vars or a secret manager — never hardcode them in frontend code or commit to Git.

If you suspect a leak, disable and recreate the Key in API Key Management immediately (effective instantly).

Common Errors & Troubleshooting

HTTPError CodeCauseHow to Fix
401invalid_api_keyKey invalid, malformed, or disabledSend with the Bearer prefix and an sk- prefix; check the status in API Key Management
402insufficient_quotaInsufficient account balanceCheck your balance on the dashboard; requests are rejected before pre-charge, so no debt is created
404model_not_foundModel not mapped or mapping disabledVerify the model name via GET /v1/models and use a model from the list
429rate_limit_exceededRate limit hit (per user × model)Lower concurrency or retry later; contact the admin for a higher quota
502upstream_errorAll upstream providers unavailableThe gateway already switched keys and channels automatically; retry later or contact the admin

For deeper investigation, include the request_id from your logs when reporting issues.

Get started, pay as you go

An API key on sign-up — change one line of base_url and start calling.

Pay as you go · No monthly fee · Balance never expires