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

# Text Generation

> Learn how to generate text with Animus models using the REST API

Animus's text generation capabilities let you create human-like text for a wide range of applications. This guide covers the fundamentals of generating text with our REST API.

## Quickstart

To generate text with Animus, you'll make a request to our chat completions endpoint. Here's a basic example using direct API calls:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Using fetch API
  const response = await fetch('https://api.animusai.co/v2/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ANIMUS_API_KEY}`
    },
    body: JSON.stringify({
      model: "vivian-llama3.1-70b-1.0-fp8",
      messages: [
        { role: "user", content: "What are the key features of deep learning?" }
      ]
    })
  });

  const data = await response.json();
  console.log(data.choices[0].message.content);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.animusai.co/v2/chat/completions"
  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {API_KEY}"  # Replace with your API key
  }

  payload = {
      "model": "vivian-llama3.1-70b-1.0-fp8",
      "messages": [
          {
              "role": "user",
              "content": "What are the key features of deep learning?"
          }
      ]
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data['choices'][0]['message']['content'])
  ```

  ```bash cURL theme={null}
  curl https://api.animusai.co/v2/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ANIMUS_API_KEY" \
    -d '{
      "model": "vivian-llama3.1-70b-1.0-fp8",
      "messages": [
        {"role": "user", "content": "What are the key features of deep learning?"}
      ]
    }'
  ```
</CodeGroup>

## Advanced Usage

### Message Roles and Names

When sending messages to the chat completions API, you can use different roles to structure your conversation:

* `system`: Provides guidance to the model on how to behave
* `user`: Represents user inputs in the conversation
* `assistant`: Represents previous responses from the model

Additionally, you can use the `name` parameter to give a specific identity to user or assistant messages. This is useful for multi-agent simulations or distinguishing between different participants in a conversation:

```javascript theme={null}
{
  "model": "vivian-llama3.1-70b-1.0-fp8",
  "messages": [
    {
      "role": "system",
      "content": "You are participating in a group discussion with users Alice and Bob."
    },
    {
      "role": "user",
      "name": "Alice",
      "content": "I think we should focus on improving user experience first."
    },
    {
      "role": "user",
      "name": "Bob",
      "content": "I disagree, I believe performance optimizations should be our priority."
    }
  ]
}
```

The `name` parameter must be a string that adheres to the following regex pattern: `^[a-zA-Z0-9_-]{1,64}$`. That means it can contain alphanumeric characters, underscores, and hyphens, with a maximum length of 64 characters.

### Controlling Response Format

You can control the format of the responses by providing specific instructions in the system or user messages:

```javascript theme={null}
{
  "model": "vivian-llama3.1-70b-1.0-fp8",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant that responds in JSON format."
    },
    {
      "role": "user",
      "content": "Provide information about planets in our solar system."
    }
  ]
}
```

### Temperature and Top P

Control the randomness and creativity of responses with these parameters:

```javascript theme={null}
{
  "model": "vivian-llama3.1-70b-1.0-fp8",
  "messages": [
    { "role": "user", "content": "Write a short poem about AI." }
  ],
  "temperature": 0.7,
  "top_p": 0.9
}
```

* **temperature**: (0-2) Lower values make output more deterministic; higher values make output more random
* **top\_p**: (0-1) Controls diversity via nucleus sampling

### Maximum Tokens

Limit the length of the response by setting a maximum token count:

```javascript theme={null}
{
  "model": "vivian-llama3.1-70b-1.0-fp8",
  "messages": [
    { "role": "user", "content": "Explain how neural networks work." }
  ],
  "max_tokens": 150
}
```

## Streaming Responses

For a more interactive experience, you can stream responses as they're generated:

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.animusai.co/v2/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ANIMUS_API_KEY}`
    },
    body: JSON.stringify({
      model: "vivian-llama3.1-70b-1.0-fp8",
      messages: [
        { role: "user", content: "Tell me a story about a space explorer." }
      ],
      stream: true
    })
  });

  // Handle the stream
  const reader = response.body.getReader();
  const decoder = new TextDecoder("utf-8");

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    // Process the received chunk
    const chunk = decoder.decode(value);
    console.log(chunk);
  }
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.animusai.co/v2/chat/completions"
  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {API_KEY}"
  }

  payload = {
      "model": "vivian-llama3.1-70b-1.0-fp8",
      "messages": [
          {"role": "user", "content": "Tell me a story about a space explorer."}
      ],
      "stream": True
  }

  response = requests.post(url, headers=headers, json=payload, stream=True)

  for line in response.iter_lines():
      if line:
          # Parse the data line
          line_text = line.decode('utf-8')
          if line_text.startswith('data: '):
              data_json = line_text[6:]  # Remove 'data: ' prefix
              if data_json != "[DONE]":
                  try:
                      chunk = json.loads(data_json)
                      content = chunk['choices'][0]['delta'].get('content', '')
                      if content:
                          print(content, end='', flush=True)
                  except json.JSONDecodeError:
                      pass
  ```

  ```bash cURL theme={null}
  curl https://api.animusai.co/v2/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ANIMUS_API_KEY" \
    -d '{
      "model": "vivian-llama3.1-70b-1.0-fp8",
      "messages": [
        {"role": "user", "content": "Tell me a story about a space explorer."}
      ],
      "stream": true
    }' \
    --no-buffer
  ```
</CodeGroup>

## Prompt Engineering Best Practices

For better results:

1. **Be specific**: Provide clear instructions with examples
2. **Use system messages**: Set the tone and behavior of the model
3. **Structure your prompts**: Break complex tasks into smaller steps
4. **Context matters**: Provide relevant background information
5. **Iterate and refine**: Test different prompts and learn what works best

## Common Use Cases

Animus's text generation can be used for:

* **Content Creation**: Generate articles, blog posts, or marketing copy
* **Conversational AI**: Build chatbots and virtual assistants
* **Code Generation**: Get help with programming tasks
* **Summarization**: Condense long texts into concise summaries
* **Translation**: Convert text between languages
* **Creative Writing**: Generate stories, poems, or scripts

## Error Handling

Implement robust error handling in your applications:

```javascript theme={null}
try {
  const response = await fetch('https://api.animusai.co/v2/chat/completions', {
    // request configuration
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error);
    // Handle specific error types
  } else {
    const data = await response.json();
    // Process successful response
  }
} catch (error) {
  console.error('Network or parsing error:', error);
  // Handle connection or parsing issues
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Vision" icon="eye" href="/rest-api-integration/vision">
    Learn how to analyze images and videos with the REST API
  </Card>

  <Card title="Moderation" icon="shield" href="/rest-api-integration/moderation">
    Implement content moderation in your applications
  </Card>

  <Card title="Webhooks" icon="webhook" href="/rest-api-integration/webhooks">
    Set up webhooks for real-time notifications
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Complete API documentation and reference
  </Card>
</CardGroup>