Skip to main content
Back to Resources

Use the CAIL Model API

Use a personal key to call current models through the CAIL Model API.

Start here

Create a personal API key

Sign in to your Dashboard and create a personal key. The complete key appears when you create it; save it immediately. Later normal listings show metadata only.

Set the API URL and key

Use the displayed CAIL Model API base URL, which currently includes the /v1 path. Type the key only at the hidden prompt. Keep the value private and ephemeral.

export CAIL_API_BASE_URL="https://tools.ailab.gc.cuny.edu/v1"
read -rs "CAIL_API_KEY?CAIL API key: "
printf '\n'
export CAIL_API_KEY

Find a model ID

Call GET /v1/models with your key. Use the exact canonical model ID returned by this request, such as gpt-oss-20b when listed. Gateway handles provider selection; availability can change with the live catalog.

curl --fail-with-body --silent --show-error \
  "$CAIL_API_BASE_URL/models" \
  --header "Authorization: Bearer $CAIL_API_KEY"

Send a chat request

Use one of the model IDs returned by /v1/models in a request to POST /v1/chat/completions.

curl --fail-with-body --silent --show-error \
  --request POST \
  "$CAIL_API_BASE_URL/chat/completions" \
  --header "Authorization: Bearer $CAIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "YOUR_RETURNED_MODEL_ID",
    "messages": [
      {"role": "user", "content": "Explain this topic in two concise sentences."}
    ],
    "stream": false
  }'

The generated text is in choices[0].message.content in the JSON response.

Understand quota and provider limits

Your allowance is shared across your personal API keys. Creating another key does not create another allowance.

quota_exceeded
A quota boundary has been reached, either for your account or for the shared service allowance. Creating another key will not add capacity; check the quota shown on your Dashboard.
upstream_rate_limited
This normalized code is specific to the /v1/run endpoint when the model service is temporarily busy. Chat Completions may instead return the provider's HTTP 429 response with Retry-After guidance.

Data handling

CAIL connections to AI providers are configured not to retain prompts or outputs. This setting does not govern account or project data stored by surrounding CAIL applications or external tools. Review the guidance for the product you are using before sending confidential material, and obtain institutional approval when required.

Recover or replace a key

If a key is lost or exposed, revoke it on your Dashboard and create a replacement. For help with access or quota, contact ailab@gc.cuny.edu. Never send the key itself by email.