Get started with the Sherlock API on CloudFerro Cloud
An application needs an API key, a model identifier, and an endpoint before it can request an answer. Sherlock provides an OpenAI-compatible API for language, vision, and embedding models. You can use curl for a first terminal request or the OpenAI Python client for an application running on your computer or a virtual machine.
The procedure below prepares the client, lists available model IDs, and sends a first chat request. The same account and project used in My Portal provide the context for the API key.
Prerequisites
No. 1 Access to a Sherlock project
Complete account and organization setup through My Portal, then create or select a project. Creating a project requires administrator privileges in the organization; for an existing project, use the access granted to your account.
No. 2 An API key for that project
Follow Authenticate with API keys to create and securely store a key. Your account needs permission to manage API keys in the selected project. Have the key available for the environment-variable setup below.
Warning
Keep the API key secret. Do not share it, commit it to a repository, or expose it in browser or mobile application code. Production requests must pass through your backend, where the key is loaded from an environment variable or a secret store.
No. 3 Tools for the examples you want to run
For Python, install Python and pip. For terminal requests, install curl. The curl commands below use Bash syntax. On Windows, use a Bash environment for those commands or run the Python examples from PowerShell.
Model types
Choose a model for the kind of result your application needs. A model ID identifies the model in an API request; copy it exactly from the models endpoint rather than assuming a name in an older example is still available.
Model type |
Use |
|---|---|
Language model |
Generate a text answer from a prompt or conversation. |
Vision-capable model |
Answer a question that includes an image as well as text. |
Embedding model |
Convert text into numerical vectors for search and similarity comparisons. |
Install the Python package
For Python requests, create and activate a virtual environment, then install the client. Skip this step if you only want to use curl.
On Linux or macOS:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install openai
On Windows PowerShell:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install openai
Configure the API key
Store the key in SHERLOCK_API_KEY in the terminal where you will run the examples. The following prompts accept the key without putting its value in the command you type or displaying it on screen.
In Bash on Linux or macOS:
read -r -s -p "Sherlock API key: " SHERLOCK_API_KEY
printf '\n'
export SHERLOCK_API_KEY
In Windows PowerShell:
$sherlockKey = Read-Host "Sherlock API key" -AsSecureString
$env:SHERLOCK_API_KEY = [System.Net.NetworkCredential]::new([string]::Empty, $sherlockKey).Password
Remove-Variable sherlockKey
The variable is available to programs launched from that terminal. Set it again in a new session, or configure it through your deployment’s secret storage. The Python examples explicitly read SHERLOCK_API_KEY and set base_url to the Sherlock service.
List available models
Use either example to query GET /models before choosing the model for a request.
With curl
curl https://api-sherlock.cloudferro.com/openai/v1/models \
-H "Authorization: Bearer $SHERLOCK_API_KEY"
With Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["SHERLOCK_API_KEY"],
base_url="https://api-sherlock.cloudferro.com/openai/v1",
)
models = client.models.list()
for model in models.data:
print(model.id)
The Python example prints the model IDs; use print(models) to inspect the full response. The chat examples below use speakleash/Bielik-11B-v3.0-Instruct. If it is absent from your response, replace it with an available chat model ID. An embedding model is not a substitute for a chat model.
Send a request with curl
Send a prompt to the chat completion endpoint. The command loads the API key from the environment and passes it as a bearer token.
curl https://api-sherlock.cloudferro.com/openai/v1/chat/completions \
-H "Authorization: Bearer $SHERLOCK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "speakleash/Bielik-11B-v3.0-Instruct",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Explain what Sherlock AI is in one paragraph."
}
]
}'
A successful request returns JSON containing the generated answer and response metadata.
Send a request with Python
The client sends the same prompt to Sherlock and prints the generated answer.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["SHERLOCK_API_KEY"],
base_url="https://api-sherlock.cloudferro.com/openai/v1",
)
response = client.chat.completions.create(
model="speakleash/Bielik-11B-v3.0-Instruct",
messages=[
{
"role": "system",
"content": "You are a helpful assistant.",
},
{
"role": "user",
"content": "Explain what Sherlock AI is in one paragraph.",
},
],
)
print(response.choices[0].message.content)
In a production application, run this logic in your backend and keep the key in an environment variable or secret store.
Troubleshooting
Missing key or authentication failure: check that SHERLOCK_API_KEY is set in the same terminal session as the command or script. Verify that the key was copied correctly and belongs to the intended Sherlock project.
Model rejected: repeat the model-listing request, copy the ID exactly, and confirm that the model supports chat requests.
Python cannot import openai: activate the virtual environment in which the client was installed. Use python -m pip install openai and run the script with that same Python interpreter.
What to do next
Compare model families in AI models and inspect the models endpoint reference.
Extend the first request with chat messages and conversation history.
Use text embeddings for vectors or vision requests for image inputs.