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

# Python SDK v2 migration

> Migrate code written against the Together Python SDK v1 to the v2 SDK.

Version 2 is the current Together Python SDK (`pip install together`). It is generated from the API spec, adds comprehensive typing, and uses `httpx` instead of `requests`. If you are starting a new project, install the SDK and follow the [quickstart](/docs/quickstart). This appendix is only for updating code written against the v1 SDK.

Core inference calls are unchanged: chat completions, streaming, embeddings, image generation, video generation, function calling, vision, and basic fine-tuning operations run without edits. The sections below cover everything that did change.

## Breaking changes

**Keyword-only arguments:** All API method arguments must be passed as keyword arguments. Positional arguments raise a `TypeError`.

```python theme={null}
# v1 (positional arguments worked)
response = client.chat.completions.create("Qwen/Qwen3.5-9B", messages)

# v2 (keyword arguments required)
response = client.chat.completions.create(
    model="Qwen/Qwen3.5-9B",
    messages=messages,
    reasoning={"enabled": False},
)
```

**Constructor parameters:** `supplied_headers` is now `default_headers`. The client also accepts two new optional parameters, `default_query` and `http_client` (an `httpx.Client`).

**Omitted parameters:** Omit optional parameters you don't set. Passing `None` raises `TypeError: Expected NotGiven, got None`.

**Extra parameters:** The v1 `**kwargs` pattern is gone. Pass additional data through `extra_body`, `extra_headers`, or `extra_query`:

```python theme={null}
response = client.chat.completions.create(
    model="Qwen/Qwen3.5-9B",
    messages=messages,
    reasoning={"enabled": False},
    extra_body={"custom_param": "value"},
)
```

**Response type imports:** Response types moved and were renamed. For example, `from together.types import ChatCompletionResponse` is now `from together.types.chat.chat_completion import ChatCompletion`.

**Removed CLI commands:** `together chat.completions`, `together completions`, and `together images generate` no longer exist.

## Renamed methods

| v1 | v2 |
| :- | :- |
| `client.batches.create_batch(file_id=...)` | `client.batches.create(input_file_id=...)` |
| `client.batches.get_batch(...)` | `client.batches.retrieve(...)` |
| `client.batches.list_batches()` | `client.batches.list()` |
| `client.batches.cancel_batch(...)` | `client.batches.cancel(...)` |
| `client.endpoints.get(...)` | `client.endpoints.retrieve(...)` |
| `client.files.retrieve_content(...)` | `client.files.content(...)` |
| `client.fine_tuning.download(...)` | `client.fine_tuning.content(...)` |
| `client.evaluation.*` | `client.evals.*` |

## Changed response and input shapes

* **List responses wrap results in `.data`:** `client.endpoints.list()`, `client.fine_tuning.list_checkpoints()`, and similar list calls return a response object. Iterate over `response.data` instead of the response itself.
* **Downloads return content instead of writing to disk:** `files.content()` and `fine_tuning.content()` return binary data. Write it to a file yourself, for example with `response.iter_bytes()` inside a `with open(path, "wb")` block.
* **Audio uploads take file objects:** `audio.transcriptions.create()` and `audio.translations.create()` require an open file object (`with open("audio.mp3", "rb") as f:`), not a path string.
* **Voice listing uses attribute access:** Iterate voices with `voice.name` instead of `voice["name"]`.
* **Checkpoint fields renamed:** `type` is now `checkpoint_type` and `timestamp` is now `created_at`. The `name` field is gone. Construct it from the job ID and `step`.
* **Endpoint autoscaling is nested:** Pass `autoscaling={"min_replicas": 1, "max_replicas": 5}` to `endpoints.create()` instead of top-level `min_replicas` and `max_replicas`.
* **Batch creation returns a wrapper:** `batches.create()` returns a response object. The job is at `response.job`.
* **Evaluations use typed parameter objects:** `evals.create()` takes a `parameters` object (for example `ParametersEvaluationClassifyParameters` from `together.types.eval_create_params`) instead of top-level keyword arguments, and `retrieve()` and `status()` take the workflow ID positionally.

## Exception changes

The base exception `TogetherException` is now `TogetherError`, and HTTP errors map to status-specific exceptions. Attribute names also changed, for example `http_status` is now `status_code`.

| v1 exception | v2 exception |
| :- | :- |
| `TogetherException` | `TogetherError` |
| `Timeout` | `APITimeoutError` |
| `ResponseError` | `APIStatusError` |
| `InvalidRequestError` | `BadRequestError` |
| `ServiceUnavailableError` | `InternalServerError` |
| `JSONError` | `APIResponseValidationError` |

`AuthenticationError`, `RateLimitError`, and `APIConnectionError` keep their names. New status-specific exceptions include `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), and `UnprocessableEntityError` (422).

## Getting help

* Browse the SDK source in the [together-py repo](https://github.com/togethercomputer/together-py).
* The [API reference](/reference/chat-completions) shows v2 code examples for every endpoint.
* Report issues on [Discord](https://discord.com/channels/1082503318624022589/1228037496257118242) or [contact support](https://www.together.ai/contact).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.