Sema Translation API - Curl Commands

🌐 Base URL

# Production
API_URL="https://sematech-sema-api.hf.space"

# Local development
# API_URL="http://localhost:8000"

🏥 Health Check Endpoints

Basic Health Check

curl -X GET "$API_URL/status"

Detailed Health Check

curl -X GET "$API_URL/health"

Metrics (if enabled)

curl -X GET "$API_URL/metrics"

🌍 Translation Endpoints

Basic Translation (Auto-detect source language)

curl -X POST "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Habari ya asubuhi",
    "target_language": "eng_Latn"
  }'

Translation with Specified Source Language

curl -X POST "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Good morning",
    "source_language": "eng_Latn",
    "target_language": "swh_Latn"
  }'

Translation with Versioned Endpoint

curl -X POST "$API_URL/api/v1/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Wĩ mwega?",
    "source_language": "kik_Latn",
    "target_language": "eng_Latn"
  }'

� Language Detection Endpoints

Detect Language of Text

curl -X POST "$API_URL/detect-language" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Habari ya asubuhi"
  }'

Detect Language (English Text)

curl -X POST "$API_URL/detect-language" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Good morning, how are you today?"
  }'

Detect Language (French Text)

curl -X POST "$API_URL/detect-language" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Bonjour, comment allez-vous?"
  }'

Detect Language (Versioned Endpoint)

curl -X POST "$API_URL/api/v1/detect-language" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hola, ¿cómo estás?"
  }'

�🗣️ Language Information Endpoints

Get All Supported Languages

curl -X GET "$API_URL/languages"

Get Popular Languages

curl -X GET "$API_URL/languages/popular"

Get African Languages

curl -X GET "$API_URL/languages/african"

Get Languages by Region

# European languages
curl -X GET "$API_URL/languages/region/Europe"

# Asian languages
curl -X GET "$API_URL/languages/region/Asia"

# African languages
curl -X GET "$API_URL/languages/region/Africa"

Search Languages

# Search for Swahili
curl -X GET "$API_URL/languages/search?q=Swahili"

# Search for Chinese
curl -X GET "$API_URL/languages/search?q=Chinese"

# Search by language code
curl -X GET "$API_URL/languages/search?q=eng"

Get Language Statistics

curl -X GET "$API_URL/languages/stats"

Get Specific Language Information

# Swahili
curl -X GET "$API_URL/languages/swh_Latn"

# English
curl -X GET "$API_URL/languages/eng_Latn"

# Chinese (Simplified)
curl -X GET "$API_URL/languages/cmn_Hans"

📚 Documentation Endpoints

Swagger UI (Open in browser)

open "$API_URL/"
# or
curl -X GET "$API_URL/"

ReDoc Documentation (Open in browser)

open "$API_URL/redoc"
# or
curl -X GET "$API_URL/redoc"

OpenAPI JSON Schema

curl -X GET "$API_URL/openapi.json"

🧪 Test Scenarios

Complete Translation Workflow

# 1. Check API health
echo "1. Health Check:"
curl -s "$API_URL/status" | jq '.status'

# 2. Get popular languages
echo "2. Popular Languages:"
curl -s "$API_URL/languages/popular" | jq '.total_count'

# 3. Validate language code
echo "3. Validate Swahili:"
curl -s "$API_URL/languages/swh_Latn" | jq '.name'

# 4. Perform translation
echo "4. Translation:"
curl -s -X POST "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{"text": "Habari ya asubuhi", "target_language": "eng_Latn"}' \
  | jq '.translated_text'

Error Testing

# Test invalid language code
curl -X GET "$API_URL/languages/invalid_code"

# Test empty translation text
curl -X POST "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{"text": "", "target_language": "eng_Latn"}'

# Test invalid search query
curl -X GET "$API_URL/languages/search?q=x"

🔧 Advanced Usage

Pretty Print JSON Response

curl -s "$API_URL/languages/popular" | jq '.'

Save Response to File

curl -s "$API_URL/languages" > all_languages.json

Check Response Headers (Including Timing)

curl -I "$API_URL/health"

View Response Headers with Translation

curl -v -X POST "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "target_language": "swh_Latn"}'

Extract Timing Headers Only

curl -s -D - -X POST "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "target_language": "swh_Latn"}' \
  | grep -E "X-Response-Time|X-Request-ID"

Measure Response Time

curl -w "@curl-format.txt" -s -o /dev/null "$API_URL/translate" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "target_language": "swh_Latn"}'

Multiple Translations (Batch Testing)

# Test multiple translations
for text in "Hello" "Good morning" "Thank you" "Goodbye"; do
  echo "Translating: $text"
  curl -s -X POST "$API_URL/translate" \
    -H "Content-Type: application/json" \
    -d "{\"text\": \"$text\", \"target_language\": \"swh_Latn\"}" \
    | jq -r '.translated_text'
  echo "---"
done

📊 Performance Testing

Simple Load Test

# Run 10 concurrent requests
for i in {1..10}; do
  curl -s -X POST "$API_URL/translate" \
    -H "Content-Type: application/json" \
    -d '{"text": "Hello world", "target_language": "swh_Latn"}' &
done
wait

Rate Limit Testing

# Test rate limiting (should hit 60 req/min limit)
for i in {1..65}; do
  echo "Request $i:"
  curl -s -X POST "$API_URL/translate" \
    -H "Content-Type: application/json" \
    -d '{"text": "Test", "target_language": "swh_Latn"}' \
    | jq -r '.translated_text // .detail'
  sleep 0.5
done

💡 Tips

Create curl-format.txt for timing

cat > curl-format.txt << 'EOF'
     time_namelookup:  %{time_namelookup}\n
        time_connect:  %{time_connect}\n
     time_appconnect:  %{time_appconnect}\n
    time_pretransfer:  %{time_pretransfer}\n
       time_redirect:  %{time_redirect}\n
  time_starttransfer:  %{time_starttransfer}\n
                     ----------\n
          time_total:  %{time_total}\n
EOF

Set API URL as environment variable

export API_URL="https://sematech-sema-api.hf.space"
# Now you can use $API_URL in all commands