Install & Compatibility
Where this runs
tested against v? · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.179s · 114.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.3s · import 1.101s · 185MB
155MB installed
● package 155MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Together
✓ from together import Together
✗ from together.api import Together
Pre-v1 had a completely different import structure. v1+ uses top-level from together import Together.
AsyncTogether
✓ from together import AsyncTogether
Async client. Same interface as Together, use with await.
OpenAI client (alternative)
✓ openai.OpenAI(api_key=os.environ['TOGETHER_API_KEY'], base_url='https://api.together.xyz/v1')
Together is fully OpenAI-compatible. Using the OpenAI client with base_url override is a valid and common pattern — no native SDK needed.
Minimal chat completion using native Together SDK
import os
from together import Together
client = Together(api_key=os.environ['TOGETHER_API_KEY'])
response = client.chat.completions.create(
model='meta-llama/Llama-3.3-70B-Instruct-Turbo',
messages=[{'role': 'user', 'content': 'Hello'}]
)
print(response.choices[0].message.content)
Debug
Known issues
breakingPre-v1 SDK (before April 2024) is completely incompatible. Different imports, different client structure, different method names. All pre-v1 tutorials and code are broken.fixpip install --upgrade together and rewrite using from together import Together pattern
affects: <1.0.0
breakingv2.0 RC is available via pip install --pre but is NOT GA. Breaking changes still possible during RC period. Do not use in production.fixUse pip install together (no --pre flag) for stable v1. Monitor GitHub for GA announcement.
affects: 2.0.0rc*
breakingv2.0 redesigns error handling entirely. TogetherException replaced with TogetherError hierarchy (APIStatusError, BadRequestError, AuthenticationError, RateLimitError). Error handling code from v1 will not catch v2 errors.fixUpdate exception handlers to catch specific v2 error types when migrating to v2.
affects: v1 → v2 migration
breakingFiles, Batches, Endpoints, Evals, and Code Interpreter APIs have updated method names and response shapes in v2. Not drop-in compatible.fixCheck the Python SDK Migration Guide for API-by-API before/after examples before upgrading.
affects: v1 → v2 migration
gotchaModel IDs use provider/model-name format (e.g. meta-llama/Llama-3.3-70B-Instruct-Turbo). LLMs frequently hallucinate incorrect Together-specific model ID formats.fixAlways verify current model IDs at https://api.together.xyz/models — they change as models are added/removed.
affects: all
gotchaTogether API is OpenAI-compatible. You can use the OpenAI Python client with base_url='https://api.together.xyz/v1' and TOGETHER_API_KEY. This is not a hack — it's documented and supported.fixIf already using OpenAI SDK, just swap base_url and api_key. No native Together SDK needed for basic chat/completions/embeddings.
affects: all
gotchaThe legacy together package (pre-v1) used TOGETHER_API_KEY but stored it differently. v1+ reads TOGETHER_API_KEY env var automatically via Together() with no argument.fixSet TOGETHER_API_KEY env var. Together() reads it automatically — no need to pass api_key= explicitly.
affects: all v1+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'together'
The Python package `together-ai` has not been installed, or the import statement uses an incorrect module name.
fixInstall the package using pip: `pip install together-ai`. The correct import is `import together`.
together.TogetherError: API key is missing or invalid.
The Together AI API key is either not provided to the client constructor, not set as an environment variable (`TOGETHER_API_KEY`), or the provided key is invalid.
fixEnsure the `TOGETHER_API_KEY` environment variable is set or pass the API key directly when instantiating the client: `client = together.Together(api_key='YOUR_API_KEY')`.
AttributeError: 'Together' object has no attribute 'Completion'
The user is attempting to access static `Completion` methods (pre-v1 API) on an instantiated `together.Together` client object (v1.0+ API), which is incorrect.
fixInstantiate the client and then use `client.completions.create` or `client.chat.completions.create`: `client = together.Together(); response = client.completions.create(...)`.
openai.AuthenticationError: No API key provided. You can set your API key in code ... or via the OPENAI_API_KEY environment variable.
When using the `openai` client with Together AI's `base_url`, the `openai` library expects the API key to be explicitly passed or the `OPENAI_API_KEY` environment variable to be set, not `TOGETHER_API_KEY`.
fixPass the Together AI API key explicitly to the OpenAI client constructor: `from openai import OpenAI; client = OpenAI(base_url='https://api.together.xyz/v1', api_key=os.environ.get('TOGETHER_API_KEY'))`. TypeError: together.completions.create() got an unexpected keyword argument 'messages'
The user is trying to pass `messages` (for chat models) to the `together.completions.create` endpoint, which expects a `prompt`.
fixUse `client.chat.completions.create(model='...', messages=[{'role': 'user', 'content': 'Hello'}])` for chat models, and `client.completions.create(model='...', prompt='Hello, world!')` for completion models. Audit
Dependencies
together>=1.0.0requiredv1 was a full rewrite in April 2024. Pre-v1 code is entirely broken.
openaioptionalOptional — can use OpenAI client with Together base_url instead of native SDK.