Text generation

SynapsAI Cloud provides powerful text generation capabilities through our OpenAI-compatible API endpoints. Our v1/chat/completions and v1/completions endpoints support advanced features including multi-modal inputs, function calling, reasoning effort control, streaming responses, and detailed output analysis.

API Compatibility

Our API is fully compatible with the OpenAI API, supporting the same v1/chat/completions and v1/completions formats. This means you can easily migrate existing OpenAI applications to SynapsAI Cloud.

Message Types and Roles

The chat completions API uses a message-based format where each message has a specific role and content. Understanding these message types is crucial for effective prompting.

The structure of messages also depends on the Jinja chat template of the tokenizer.

Message Roles

system: Provides context and instructions to the model about how to behave
user: Contains the user’s input or question
assistant: Contains the model’s previous responses in a conversation

Message Content Types

Messages can contain different types of content:

Text Content

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
]

curl -X POST https://api.synapsai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is the capital of France?"}
        ]
    }'

You can include images, audios and videos in your messages by providing a URL or base64-encoded image data:

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is shown in this image?"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/image.jpg"
                }
            }
        ]
    }
]

curl -X POST https://api.synapsai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "What is shown in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    }
                }
            ]
        }]
    }'

Supported image formats include JPEG, PNG, GIF, and WebP. For base64 encoding, use the format: data:image/jpeg;base64,{base64_string}

Conversation Context

Include previous assistant responses to maintain conversation context:

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What about its population?"}
]

curl -X POST https://api.synapsai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is the capital of France?"},
            {"role": "assistant", "content": "The capital of France is Paris."},
            {"role": "user", "content": "What about its population?"}
        ]
    }'

Advanced Parameters

Control the model’s behavior with these key parameters:

Generation Parameters

temperature (0.0-2.0): Controls randomness. Lower values make output more deterministic
top_p (0.0-1.0): Nucleus sampling parameter
top_k (0-100): Top-k sampling parameter
max_completion_tokens: Maximum number of tokens to generate
stop: Stop generation when these strings are encountered

response = model.chat.completions.create(
    model="model-id",
    messages=[{"role": "user", "content": "Write a short story"}],
    temperature=0.8,
    top_p=0.9,
    top_k=50,
    max_completion_tokens=200,
    stop=["\n", "Human:"]
)

curl -X POST https://api.synapsai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "messages": [{"role": "user", "content": "Write a short story"}],
        "temperature": 0.8,
        "top_p": 0.9,
        "top_k": 50,
        "max_completion_tokens": 200,
        "stop": ["\n", "Human:"]
    }'

Output Parameters

logprobs: Return log probabilities for tokens
top_logprobs: Number of most likely tokens to return at each position

response = model.chat.completions.create(
    model="model-id",
    messages=[{"role": "user", "content": "Hello"}],
    logprobs=True,
    top_logprobs=3
)

# Access log probabilities
for choice in response.choices:
    for logprob in choice.logprobs.content:
        print(f"Token: {logprob.token}, Logprob: {logprob.logprob}")

curl -X POST https://api.synapsai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "messages": [{"role": "user", "content": "Hello"}],
        "logprobs": true,
        "top_logprobs": 3
    }'

Function Calling and Tools

The chat completions endpoint supports tools, tool_choice, and reasoning_effort. See the dedicated tool calling guide for examples, including how we parse tool calls from model responses and a manual parsing fallback when automatic parsing does not work for your model.

Streaming Responses

Process responses in real-time as they are generated using streaming:

response = model.chat.completions.create(
    model="model-id",
    messages=[{"role": "user", "content": "Tell me a long story"}],
    stream=True
)

full_response = ""
for chunk in response:
    if chunk.choices[0].delta.content:
        content = chunk.choices[0].delta.content
        print(content, end="", flush=True)
        full_response += content

curl -X POST https://api.synapsai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "messages": [{"role": "user", "content": "Tell me a long story"}],
        "stream": true
    }' \
  --no-buffer

Response Analysis

Understanding Finish Reasons

The finish_reason field indicates why generation stopped:

stop: Generation completed normally (hit max_tokens or a stop sequence)
length: Generation stopped due to reaching max_tokens

response = model.chat.completions.create(
    model="model-id",
    messages=[{"role": "user", "content": "Hello"}],
    max_tokens=10
)

print(f"Finish reason: {response.choices[0].finish_reason}")
print(f"Generated text: {response.choices[0].message.content}")
print(f"Tokens used: {response.usage.total_tokens}")

Token Usage and Costs (for per-token pricing)

Monitor your API usage and costs:

response = model.chat.completions.create(
    model="model-id",
    messages=[{"role": "user", "content": "Write a short story"}]
)

print(f"Prompt tokens: {response.usage.prompt_tokens}")
print(f"Completion tokens: {response.usage.completion_tokens}")
print(f"Total tokens: {response.usage.total_tokens}")

Practical Examples

Creative Writing

Generate creative content with specific instructions:

response = model.chat.completions.create(
    model="model-id",
    messages=[
        {"role": "system", "content": "You are a creative writing assistant. Write in a poetic, descriptive style."},
        {"role": "user", "content": "Write a short story about a robot learning to paint"}
    ],
    temperature=0.9,
    max_completion_tokens=300
)

Code Generation

Generate code with specific requirements:

response = model.chat.completions.create(
    model="model-id",
    messages=[
        {"role": "system", "content": "You are an expert Python developer. Provide only the code without explanation."},
        {"role": "user", "content": "Write a function that calculates fibonacci numbers using memoization"}
    ],
    temperature=0.1
)

Data Analysis

Analyze and summarize data:

response = model.chat.completions.create(
    model="model-id",
    messages=[
        {"role": "system", "content": "You are a data analyst. Provide clear, structured analysis."},
        {"role": "user", "content": "Analyze these sales numbers: Q1: $100k, Q2: $150k, Q3: $120k, Q4: $200k. What trends do you see?"}
    ],
    temperature=0.3
)

Best Practices

Prompt Engineering

Be specific and provide context in system messages
Use structured formats for complex tasks
Experiment with temperature and other parameters
Provide examples in your prompts (few-shot learning)

Error Handling

Always handle API errors gracefully:

try:
    response = model.chat.completions.create(
        model="model-id",
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.choices[0].message.content)
except Exception as e:
    print(f"Error: {e}")

Basic Completions API

For simple text generation without conversation context, use the completions endpoint. This endpoint supports everything in the chat completions endpoint, except for the messages parameter that becomes prompt, and the tools parameter that is not supported. We also support providing images, audio, and video files to the completions endpoint.

response = model.completions.create(
    model="model-id",
    prompt="The capital of France is",
    max_completion_tokens=50,
    temperature=0.7
)

curl -X POST https://api.synapsai.cloud/v1/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "prompt": "The capital of France is",
        "max_completion_tokens": 50,
        "temperature": 0.7
    }'

Some models require a special image token (e.g. <image>) to be placed directly in the prompt to indicate where the image should be referenced. If the model you’re using requires one, we recommend placing it manually in your prompt for best results — for example: "<image>\nDescribe this image.". If no token is present, our backend will attempt to inject it automatically. The same happens for audio and video files.

response = model.completions.create(
    model="model-id",
    prompt="The capital of France is",
    max_completion_tokens=50,
    temperature=0.7,
    images=["https://example.com/image.jpg"],
    videos=["https://example.com/video.mp4"],
    audio=["https://example.com/audio.mp3"]
)

curl -X POST https://api.synapsai.cloud/v1/completions \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "model-id",
        "prompt": "The capital of France is",
        "max_completion_tokens": 50,
        "temperature": 0.7,
        "images": ["https://example.com/image.jpg"],
        "videos": ["https://example.com/video.mp4"],
        "audio": ["https://example.com/audio.mp3"]
    }'

For quick prototyping and testing, you can also try generating text using the Playground. For deeper insights into the v1/chat/completions and v1/completions endpoints, see our API reference.

Getting started

Guides

Examples

Manage

Platform

Resources

Support

Legal

API Compatibility

Message Types and Roles

Message Roles

Message Content Types

Text Content

Conversation Context

Advanced Parameters

Generation Parameters

Output Parameters

Function Calling and Tools

Streaming Responses

Response Analysis

Understanding Finish Reasons

Token Usage and Costs (for per-token pricing)

Practical Examples

Creative Writing

Code Generation

Data Analysis

Best Practices

Prompt Engineering

Error Handling

Basic Completions API

​API Compatibility

​Message Types and Roles

​Message Roles

​Message Content Types

​Text Content

​Multi-modal Content

​Conversation Context

​Advanced Parameters

​Generation Parameters

​Output Parameters

​Function Calling and Tools

​Streaming Responses

​Response Analysis

​Understanding Finish Reasons

​Token Usage and Costs (for per-token pricing)

​Practical Examples

​Creative Writing

​Code Generation

​Data Analysis

​Best Practices

​Prompt Engineering

​Error Handling

​Basic Completions API

​Example with multi-modal inputs

API Compatibility

Message Types and Roles

Message Roles

Message Content Types

Text Content

Multi-modal Content

Conversation Context

Advanced Parameters

Generation Parameters

Output Parameters

Function Calling and Tools

Streaming Responses

Response Analysis

Understanding Finish Reasons

Token Usage and Costs (for per-token pricing)

Practical Examples

Creative Writing

Code Generation

Data Analysis

Best Practices

Prompt Engineering

Error Handling

Basic Completions API

Example with multi-modal inputs