Set up your shell and check the endpoint
Get a key from the API key page, then export it along with the base URL so you do not paste secrets into every command.
export API_KEY="paste-your-key-here"
export BASE="https://api.uncensoredllmapi.com/v1"
Every request sends the key as a bearer token in the Authorization header. Request bodies are JSON, so add Content-Type: application/json when you POST. The maximum body size is 8 MB, which only matters if you paste very large documents into the prompt.
The examples use the single quotes of a Unix shell. On Windows PowerShell, put the JSON in a file and pass it with --data @body.json to avoid quoting trouble.
The cheapest sanity check is a GET that lists the models. It confirms the key and the URL, and it costs nothing.
curl -s "$BASE/models" \
-H "Authorization: Bearer $API_KEY"
The data array in the reply should include the ID uncensored. A 401 means the key is missing or mistyped. If curl cannot connect at all, check the host in $BASE and make sure it ends in /v1 with no extra path.
1. Send a chat completion
This is the request every OpenAI-style client sends under the hood.
curl -s "https://api.uncensoredllmapi.com/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are a concise assistant."},
{"role": "user", "content": "Give me three names for a fantasy tavern."}
],
"temperature": 0.8,
"max_tokens": 200
}'
The reply is JSON. The text sits at choices[0].message.content, and the token counts are in usage. Pipe the output through jq -r '.choices[0].message.content' if you have jq installed and only want the text. The max_tokens field is optional; leave it out and the completion may use whatever is left of the 100,000-token window.
The newer POST /v1/responses endpoint is also available if your client uses that format. For the full list of parameters, see the documentation.
2. Stream the answer
Add "stream": true and tell curl not to buffer with -N. Tokens will print as they are generated.
curl -N "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to ten in words."}]
}'
Each line begins with data: and holds a small JSON chunk with a delta. The last events carry usage, and the stream finishes with data: [DONE]. Without -N curl waits for a full buffer, and the output looks like it arrives in one lump. Note that a streamed request keeps one concurrency slot busy until it ends.
3. Ask for JSON
For output that a script will parse, switch on JSON mode with response_format. Mention the word JSON in the prompt so the model knows what shape you expect.
curl -s "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"response_format": {"type": "json_object"},
"messages": [{"role": "user",
"content": "Return JSON with keys name and level for a fantasy character."}]
}' | jq -r '.choices[0].message.content | fromjson'
The final fromjson filter parses the string inside content, so jq fails loudly if the model returned something that is not valid JSON. That makes it a handy quick test. More patterns are on the JSON mode page.
4. Try a tool call
Tool calling lets the model ask your code to run a function. You describe the function in a tools array, and if the model decides to use it, the reply holds a tool_calls entry instead of text.
curl -s "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is the weather in Oslo?"}],
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}],
"tool_choice": "auto"
}' | jq '.choices[0].message.tool_calls'
You should get a function name and a JSON string of arguments. Your code runs the function, then sends a second request that repeats the earlier messages, adds the assistant message with the tool call, and adds a message with role: "tool" holding the result. The model then writes the final answer.
5. Check headers and balance
Add -i to see response headers along with the body. You will find X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests and X-RateLimit-Limit-Concurrency.
curl -s -i "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' \
| grep -i "^x-"
curl -s "$BASE/balance" -H "Authorization: Bearer $API_KEY"
The second call returns your credit directly. OpenAI-style tools can use GET /v1/dashboard/billing/credit_grants instead. A tiny request like the one above costs a fraction of a cent: with 10 input tokens and 5 output tokens the price is 10 x 0.15 / 1,000,000 + 5 x 0.50 / 1,000,000 = $0.000004. See the pricing page for the rates.
A reusable smoke-test script
Once you trust the individual calls, wrap them in a short script you can run after any deploy, key rotation or network change. It fails on the first problem, so you see exactly which step broke.
set -euo pipefail
BASE="https://api.uncensoredllmapi.com/v1"
echo "models:"
curl -sf "$BASE/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[].id'
echo "chat:"
curl -sf "$BASE/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"uncensored","messages":[{"role":"user","content":"Say ok."}],"max_tokens":5}' \
| jq -r '.choices[0].message.content'
echo "balance:"
curl -sf "$BASE/balance" -H "Authorization: Bearer $API_KEY"
The -f flag makes curl exit with an error on HTTP failures, and set -e stops the script there. Put it in a cron job or a CI step if you run a service on top of this API and want an early warning when something changes. Keep the key in a secret store or environment variable, never in the script file itself.
When you vary the request, try one setting at a time: temperature for randomness, top_p for nucleus sampling, stop for custom end sequences, and seed for repeatable output. All of them are passed through to the model, so you can compare their effect from the same terminal history.
Reading errors from curl
| Status | Likely cause | Fix |
|---|---|---|
| 401 | Missing or wrong key | Check the Authorization header and that $API_KEY is exported |
| 400 | Malformed JSON or bad field | Validate the body with jq . before sending |
429, code rate_limited | More than 300 requests per minute (60 on a trial key) | Slow down your loop |
429, code concurrency | More than 8 requests at once (2 on a trial key) | Run fewer parallel jobs |
429 with Retry-After: 5 | Temporary overload | Wait 5 seconds and retry |
Add -w "\n%{http_code}\n" to print the status code after the body, which saves you from guessing. Error bodies are JSON with a message and a code, so jq .error shows them cleanly. If you see a 429 in a loop, do not retry instantly; a pause of a few seconds lets the minute window and the concurrent slots clear, and a tight retry loop only keeps you over the limit. A trial key has tighter limits than a full key, so a script that works after your first top-up may fail on trial credit if it runs jobs in parallel. Once the requests behave, move to an SDK; the same URL and model name carry over unchanged. New accounts can claim $0.50 of trial credit with one click, enough for hundreds of small test calls. Top-ups after that start at $20 and are paid in crypto (USDT on TRC20 or USDC on Base).
