Skip to main content

cURL / HTTP

Make direct HTTP requests to the platform API using cURL or any HTTP client. This is useful for testing, scripting, or languages without an official OpenAI SDK.

Basic Setup​

Set your API key:

export API_KEY="sk-proj-your-api-key"
export BASE_URL="https://api.bulutistan.ai/v1"

Chat Completions​

Basic Request​

curl $BASE_URL/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-chat-model",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is machine learning?"}
    ]
  }'

With Parameters​

curl $BASE_URL/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-chat-model",
    "messages": [
      {"role": "user", "content": "Write a short poem"}
    ],
    "max_tokens": 100,
    "temperature": 0.8,
    "top_p": 0.9
  }'

Streaming​

curl $BASE_URL/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -N \
  -d '{
    "model": "your-chat-model",
    "messages": [
      {"role": "user", "content": "Tell me a story"}
    ],
    "stream": true
  }'

The -N flag disables buffering for real-time output.

Multi-turn Conversation​

curl $BASE_URL/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-chat-model",
    "messages": [
      {"role": "system", "content": "You are a coding assistant."},
      {"role": "user", "content": "How do I read a file in Python?"},
      {"role": "assistant", "content": "You can use the built-in open() function..."},
      {"role": "user", "content": "Show me an example with error handling"}
    ]
  }'

Embeddings​

curl $BASE_URL/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-embedding-model",
    "input": "Text to embed into a vector"
  }'

Multiple Inputs​

curl $BASE_URL/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-embedding-model",
    "input": [
      "First document",
      "Second document",
      "Third document"
    ]
  }'

List Models​

curl $BASE_URL/models \
  -H "Authorization: Bearer $API_KEY"

Get Model Details​

# URL encode the model ID if it contains a slash (/ becomes %2F)
curl "$BASE_URL/models/your-chat-model" \
  -H "Authorization: Bearer $API_KEY"

Text Completions​

curl $BASE_URL/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "your-chat-model",
    "prompt": "Once upon a time",
    "max_tokens": 100,
    "temperature": 0.7
  }'

Useful Options​

Pretty Print JSON​

curl ... | jq .

Save Response​

curl ... -o response.json

Verbose Output​

curl -v ...

Silent Mode (No Progress)​

curl -s ...

Include Headers​

curl -i ...

Timing​

curl -w "\nTime: %{time_total}s\n" ...

Shell Script Example​

#!/bin/bash

API_KEY="${OPENAI_API_KEY}"
BASE_URL="${OPENAI_BASE_URL:-https://api.bulutistan.ai/v1}"

chat() {
    local message="$1"
    curl -s "$BASE_URL/chat/completions" \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $API_KEY" \
        -d "{
            \"model\": \"your-chat-model\",
            \"messages\": [{\"role\": \"user\", \"content\": \"$message\"}]
        }" | jq -r '.choices[0].message.content'
}

# Usage
chat "Hello, how are you?"

Error Handling​

Check HTTP status:

response=$(curl -s -w "\n%{http_code}" $BASE_URL/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"model": "...", "messages": [...]}')

http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -eq 200 ]; then
    echo "$body" | jq .
else
    echo "Error $http_code: $body"
fi

Windows (PowerShell)​

$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer sk-proj-your-api-key"
}

$body = @{
    model = "your-chat-model"
    messages = @(
        @{ role = "user"; content = "Hello" }
    )
} | ConvertTo-Json

Invoke-RestMethod -Uri "https://api.bulutistan.ai/v1/chat/completions" `
    -Method Post `
    -Headers $headers `
    -Body $body