> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Text generation

> Generate text from text with SynapsAI Cloud

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.

<Note>
  The structure of messages also depends on the Jinja chat template of the tokenizer.
</Note>

### 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

<CodeGroup>
  ```python title="Python" theme={null}
  messages = [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
  ]
  ```

  ```curl title="cURL" theme={null}
  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?"}
          ]
      }'
  ```
</CodeGroup>

#### Multi-modal Content

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

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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"
                      }
                  }
              ]
          }]
      }'
  ```
</CodeGroup>

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

### Conversation Context

Include previous assistant responses to maintain conversation context:

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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?"}
          ]
      }'
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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:"]
      }'
  ```
</CodeGroup>

### Output Parameters

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

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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
      }'
  ```
</CodeGroup>

## Function Calling and Tools

The chat completions endpoint supports `tools`, `tool_choice`, and `reasoning_effort`. See the dedicated [tool calling guide](/examples/tool-calling) 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:

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python title="Python" theme={null}
  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}")
  ```
</CodeGroup>

### Token Usage and Costs *(for per-token pricing)*

Monitor your API usage and costs:

<CodeGroup>
  ```python title="Python" theme={null}
  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}")
  ```
</CodeGroup>

## Practical Examples

### Creative Writing

Generate creative content with specific instructions:

<CodeGroup>
  ```python title="Python" theme={null}
  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
  )
  ```
</CodeGroup>

### Code Generation

Generate code with specific requirements:

<CodeGroup>
  ```python title="Python" theme={null}
  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
  )
  ```
</CodeGroup>

### Data Analysis

Analyze and summarize data:

<CodeGroup>
  ```python title="Python" theme={null}
  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
  )
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```python title="Python" theme={null}
  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}")
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```python title="Python" theme={null}
  response = model.completions.create(
      model="model-id",
      prompt="The capital of France is",
      max_completion_tokens=50,
      temperature=0.7
  )
  ```

  ```curl title="cURL" theme={null}
  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
      }'
  ```
</CodeGroup>

### Example with multi-modal inputs

<Note>
  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.
</Note>

<CodeGroup>
  ```python title="Python" theme={null}
  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 title="cURL" theme={null}
  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"]
      }'
  ```
</CodeGroup>

<Tip>
  For quick prototyping and testing, you can also try generating text using the [Playground](https://platform.synapsai.cloud/playground). For deeper insights into the `v1/chat/completions` and `v1/completions` endpoints, see our [API reference](https://docs.synapsai.cloud/api-reference/create-a-chat-completion).
</Tip>