🛠️ Standardized API Calling Templates for SambaCloud Models

Knowledge Articles
1

This document outlines standardized calling templates for all model offerings in SambaCloud, categorized by modality and capability. It includes key differences between each API usage pattern to ensure clarity and consistency for developers and users.

:locked_with_key: Authentication

All requests must include an API key:

-H "Authorization: Bearer <your-api-key>"

:books: Model Categories & Usage Templates

:brain: Reasoning Models

These models are designed for complex reasoning, instruction following, and task planning.

Model Name Size
DeepSeek-R1-0528 671B
DeepSeek-R1-Distill-Llama-70B 70B
Qwen3-32B 32B

:white_check_mark: Template

curl -H "Authorization: Bearer <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "stream": true,
           "model": "<model-name>",
           "messages": [
               {
                   "role": "system",
                   "content": "You are a helpful assistant"
               },
               {
                   "role": "user",
                   "content": "Hello"
               }
           ]
         }' \
     -X POST https://api.sambanova.ai/v1/chat/completions

:white_check_mark: Same template used for all Reasoning and Text models

:memo: Text Generation Models

Optimized for fast, fluent natural language generation and summarization.

Model Name Size
DeepSeek-V3-0324 671B
Llama-3.3-Swallow-70B-Instruct-v0.4 70B
Meta-Llama-3.1-8B-Instruct 8B
Meta-Llama-3.3-70B-Instruct 70B

:white_check_mark: Template

Identical to Reasoning models:

curl -H "Authorization: Bearer <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "stream": true,
           "model": "<model-name>",
           "messages": [
               {
                   "role": "system",
                   "content": "You are a helpful assistant"
               },
               {
                   "role": "user",
                   "content": "Hello"
               }
           ]
         }' \
     -X POST https://api.sambanova.ai/v1/chat/completions

:framed_picture: Image + Text (Multimodal)

Capable of interpreting visual input and combining it with language understanding.

Model Name
Llama-4-Maverick-17B-128E-Instruct

🆇 Difference in Template

Instead of plain string content, the “messages” block uses structured content with type: “text” and type: “image_url” entries.

:white_check_mark: Template

curl -H "Authorization: Bearer <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "stream": true,
           "model": "Llama-4-Maverick-17B-128E-Instruct",
           "messages": [
               {
                   "role": "user",
                   "content": [
                       {
                           "type": "text",
                           "text": "What do you see in this image?"
                       },
                       {
                           "type": "image_url",
                           "image_url": {
                               "url": "<image_in_base_64>"
                           }
                       }
                   ]
               }
           ]
         }' \
     -X POST https://api.sambanova.ai/v1/chat/completions

:speaker_medium_volume: Audio / Text (Transcription)

Used to transcribe audio files using Whisper-like models.

Model Name Note
Whisper-Large-v3 Beta

🆇 Difference in Template

This is a multipart/form-data POST request to a different endpoint, not JSON.

:white_check_mark: Template

curl --location 'https://api.sambanova.ai/v1/audio/transcriptions' \
     --header 'Authorization: Bearer <your-api-key>' \
     --form 'model="Whisper-Large-v3"' \
     --form 'language="spanish"' \
     --form 'response_format="json"' \
     --form 'file=@"/path/to/audio/file.mp3"' \
     --form 'stream="true"'

:warning: Summary of Differences

Model Type Endpoint Body Type Notes
Text / Reasoning /v1/chat/completions JSON Standard messages array
Image + Text /v1/chat/completions JSON Requires structured image content format
Audio / Text /v1/audio/transcriptions multipart/form-data Separate endpoint, file upload required

:pushpin: Best Practices

  • :white_check_mark: Always validate the model name from the official model list
  • :white_check_mark: Set “stream”: true for real-time output
  • :white_check_mark: Include a system role for consistent personality/context
  • :white_check_mark: Use proper formatting for multimodal models
  • :cross_mark: Do not use chat JSON format for audio transcription
3 Likes