Hugging Face inference quickstart

Together AI is an inference provider on the Hugging Face Hub. You can call Together models through the Hugging Face client libraries, the OpenAI client, or directly from model page widgets on the Hub.

Authentication and billing

When using Together AI through Hugging Face, you have two options for authentication:

Direct requests: Add your Together AI API key to your Hugging Face user account settings. Inference requests are sent directly to Together AI, and billing is handled by your Together AI account.
Routed requests: If you don’t configure a Together AI API key, your requests are routed through Hugging Face and authenticated with a Hugging Face token. Billing for routed requests is applied to your Hugging Face account at standard provider API rates. You don’t need a Together AI account for this option.

To add a Together AI API key to your Hugging Face settings:

Go to your Hugging Face inference provider settings.
Add your Together AI API key under the Together AI provider.
Optionally, set your preferred provider order, which controls the display order in model widgets and code snippets.

You can browse all Together AI models on the Hub and try them directly in the model page widget.

Installation

Install the Hugging Face client for your language:

pip install "huggingface_hub>=0.29.0"

npm install @huggingface/inference

Chat completions

Pass provider="together" to route the request to Together AI. The API key can be a Together AI key (direct requests) or a Hugging Face token (routed requests).

from huggingface_hub import InferenceClient

client = InferenceClient(
    provider="together",
    api_key="your_api_key",  # Together AI key or Hugging Face token
)

completion = client.chat.completions.create(
    model="moonshotai/Kimi-K3",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    max_tokens=500,
)

print(completion.choices[0].message)

import { InferenceClient } from "@huggingface/inference";

const client = new InferenceClient("your_api_key"); // Together AI key or Hugging Face token

const chatCompletion = await client.chatCompletion({
  model: "moonshotai/Kimi-K3",
  messages: [{ role: "user", content: "What is the capital of France?" }],
  provider: "together",
  max_tokens: 500,
});

console.log(chatCompletion.choices[0].message);

In @huggingface/inference v3 and later, the HfInference class is a deprecated alias slated for removal. Use InferenceClient instead.

Kimi K3 reasons by default, so the message includes a reasoning_content field alongside content. The Hugging Face clients only forward their own parameter set, so you can’t pass Together-specific parameters like reasoning through them. If you need to control reasoning, call the Together API directly. You can swap in any Together AI text model on the Hub.

OpenAI client library

You can also reach Together models through Hugging Face’s OpenAI-compatible router with the OpenAI Python client. The router requires a Hugging Face token. Append :together to the model ID to pin the provider:

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://router.huggingface.co/v1",
    api_key="your_hf_token",
)

completion = client.chat.completions.create(
    model="moonshotai/Kimi-K3:together",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    max_tokens=500,
)

print(completion.choices[0].message)

You can copy a ready-made snippet from any model page on the Hub.

Other modalities

The Hub’s provider mapping for Together AI currently covers text generation, speech recognition, and embeddings. For image generation and text-to-speech, call the Together API directly. Start with the image generation overview.

GUIDES

MODEL QUICKSTARTS

BUILD APPS

BUILD AGENTS

WORK WITH CODING AGENTS

SDK INTEGRATIONS

Hugging Face inference quickstart

Authentication and billing

Installation

Chat completions

OpenAI client library

Other modalities

​Authentication and billing

​Installation

​Chat completions

​OpenAI client library

​Other modalities

Authentication and billing

Installation

Chat completions

OpenAI client library

Other modalities