Build a chat API on Render

Using a coding agent? Load the together-chat-completions skill to teach your agent to write correct chat completions code for Together AI. Learn more.

This guide walks through building and deploying a single-turn chat API. You will create a small web service that accepts an authenticated POST /chat request, forwards the message to Together AI’s chat completions API, and returns the model’s reply as JSON. You can follow the guide in TypeScript with Express or in Python with FastAPI. Both versions call https://api.together.ai/v1/chat/completions, default to Qwen3.5 9B, expose an unauthenticated GET /health endpoint for Render health checks, protect POST /chat with a separate bearer token, and stop an inference request after 60 seconds.

Architecture

A trusted client sends an authenticated POST /chat request to the Render web service, which calls Together AI and returns the reply, model ID, and token usage. CHAT_API_KEY authenticates the caller on the first hop, and TOGETHER_API_KEY stays inside the service.

Each request follows four steps. The client sends a bearer token and a message to the Render service. The service validates both. The service sends one chat completion request to Together AI. The service returns the reply, model ID, and token usage to the client. The service uses two separate secrets. CHAT_API_KEY authenticates the caller, and TOGETHER_API_KEY authenticates the server-to-server request to Together AI.

Prerequisites

Before you start, make sure you have:

A Together AI account with an active credit balance.
A project-scoped Together API key.
A Render account.
A GitHub, GitLab, or Bitbucket account.
Node.js 22 through 24 for the TypeScript path, or Python 3.10 or later for the Python path.

You also need a secret that callers will use to authenticate with your chat API. Generate one and save it in a password manager:

Shell

openssl rand -hex 32

This value becomes CHAT_API_KEY. It is different from your TOGETHER_API_KEY.

The shared CHAT_API_KEY is a minimal guard for a server-to-server demo. Do not embed it in browser or mobile application code. For a public application, add user authentication, per-user authorization, and rate limits.

Step 1: Create the project

Create a new directory and initialize a Git repository:

Shell

mkdir together-render-chat
cd together-render-chat
git init

Create a subdirectory for the runtime you want to use. You only need the files for the path you select.

mkdir ts
cd ts

mkdir python
cd python

For the TypeScript path, create package.json:

ts/package.json

{
  "name": "together-render-chat",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=22 <25"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  },
  "dependencies": {
    "express": "^5.2.1"
  },
  "devDependencies": {
    "@types/express": "^5.0.6",
    "@types/node": "^24.13.3",
    "typescript": "^7.0.2"
  }
}

Then create tsconfig.json:

ts/tsconfig.json

{
  "compilerOptions": {
    "outDir": "dist",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2023",
    "strict": true,
    "skipLibCheck": true
  }
}

Install the dependencies and compile the project:

Shell

npm install
npm run build
cd ..

Commit the generated ts/package-lock.json. The Render build uses npm ci, which requires this file. For the Python path, create requirements.txt instead:

python/requirements.txt

fastapi==0.141.1
uvicorn[standard]==0.52.0
httpx==0.28.1

Verify the dependencies in an isolated environment:

Shell

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd ..

Step 2: Add the chat handler

The handler validates the caller before it makes a billable request to Together AI. It also limits the message to 8,000 characters and maps upstream failures to explicit HTTP responses.

import { timingSafeEqual } from "node:crypto";
import express, { type ErrorRequestHandler } from "express";

const app = express();
app.use(express.json({ limit: "16kb" }));

const TOGETHER_URL = "https://api.together.ai/v1/chat/completions";
const MODEL = process.env.TOGETHER_MODEL ?? "Qwen/Qwen3.5-9B";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required.`);
  return value;
}

const TOGETHER_API_KEY = requiredEnv("TOGETHER_API_KEY");
const CHAT_API_KEY = requiredEnv("CHAT_API_KEY");

type TogetherResponse = {
  model?: string;
  choices?: Array<{ message?: { content?: string | null } }>;
  usage?: unknown;
};

function isAuthorized(header: string | undefined): boolean {
  if (!header?.startsWith("Bearer ")) return false;

  const supplied = Buffer.from(header.slice(7));
  const expected = Buffer.from(CHAT_API_KEY);
  return (
    supplied.length === expected.length && timingSafeEqual(supplied, expected)
  );
}

app.get("/health", (_req, res) => {
  res.json({ ok: true, model: MODEL });
});

app.post("/chat", async (req, res) => {
  if (!isAuthorized(req.get("authorization"))) {
    return res.status(401).json({ error: "Unauthorized" });
  }

  const message = req.body?.message;
  if (typeof message !== "string" || !message.trim() || message.length > 8000) {
    return res.status(400).json({
      error:
        'Body must include a non-empty "message" string of at most 8000 characters.',
    });
  }

  try {
    const upstream = await fetch(TOGETHER_URL, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${TOGETHER_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: MODEL,
        messages: [{ role: "user", content: message.trim() }],
        reasoning: { enabled: false },
        max_tokens: 512,
      }),
      signal: AbortSignal.timeout(60_000),
    });

    if (!upstream.ok) {
      const detail = (await upstream.text()).slice(0, 500);
      console.error("Together error", upstream.status, detail);
      return res.status(502).json({
        error: "Upstream inference failed",
        upstreamStatus: upstream.status,
      });
    }

    const data = (await upstream.json()) as TogetherResponse;
    const reply = data.choices?.[0]?.message?.content;
    if (typeof reply !== "string" || !reply) {
      return res
        .status(502)
        .json({ error: "Together returned an invalid response." });
    }

    return res.json({
      model: data.model ?? MODEL,
      reply,
      usage: data.usage,
    });
  } catch (error) {
    if (error instanceof DOMException && error.name === "TimeoutError") {
      return res
        .status(504)
        .json({ error: "Together timed out after 60 seconds." });
    }

    console.error("Together request failed", error);
    return res.status(502).json({ error: "Could not reach Together." });
  }
});

const requestErrorHandler: ErrorRequestHandler = (error, _req, res, _next) => {
  const type =
    typeof error === "object" && error !== null && "type" in error
      ? String(error.type)
      : "";

  if (type === "entity.parse.failed") {
    return res.status(400).json({ error: "Request body must be valid JSON." });
  }
  if (type === "entity.too.large") {
    return res.status(413).json({ error: "Request body is too large." });
  }

  console.error("Unhandled request error", error);
  return res.status(500).json({ error: "Internal server error." });
};
app.use(requestErrorHandler);

const port = Number(process.env.PORT) || 3000;
app.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));

import os
import secrets

import httpx
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel

TOGETHER_URL = "https://api.together.ai/v1/chat/completions"
MODEL = os.environ.get("TOGETHER_MODEL", "Qwen/Qwen3.5-9B")
TOGETHER_API_KEY = os.environ["TOGETHER_API_KEY"]
CHAT_API_KEY = os.environ["CHAT_API_KEY"]

app = FastAPI()


class ChatRequest(BaseModel):
    message: str


@app.get("/health")
def health():
    return {"ok": True, "model": MODEL}


@app.post("/chat")
async def chat(
    req: ChatRequest,
    authorization: str | None = Header(default=None),
):
    supplied_key = (
        authorization.removeprefix("Bearer ")
        if authorization and authorization.startswith("Bearer ")
        else ""
    )
    if not supplied_key or not secrets.compare_digest(
        supplied_key, CHAT_API_KEY
    ):
        raise HTTPException(
            status_code=401,
            detail="Unauthorized",
            headers={"WWW-Authenticate": "Bearer"},
        )

    message = req.message.strip()
    if not message or len(message) > 8000:
        raise HTTPException(
            status_code=400,
            detail='Field "message" must contain 1 to 8000 characters.',
        )

    try:
        async with httpx.AsyncClient(timeout=60.0) as client:
            upstream = await client.post(
                TOGETHER_URL,
                headers={"Authorization": f"Bearer {TOGETHER_API_KEY}"},
                json={
                    "model": MODEL,
                    "messages": [{"role": "user", "content": message}],
                    "reasoning": {"enabled": False},
                    "max_tokens": 512,
                },
            )
    except httpx.TimeoutException as exc:
        raise HTTPException(
            status_code=504,
            detail="Together timed out after 60 seconds.",
        ) from exc
    except httpx.RequestError as exc:
        raise HTTPException(
            status_code=502,
            detail="Could not reach Together.",
        ) from exc

    if not upstream.is_success:
        print("Together error", upstream.status_code, upstream.text)
        raise HTTPException(
            status_code=502,
            detail={
                "message": "Upstream inference failed",
                "upstream_status": upstream.status_code,
            },
        )

    try:
        data = upstream.json()
        reply = data["choices"][0]["message"]["content"]
    except (ValueError, KeyError, IndexError, TypeError) as exc:
        raise HTTPException(
            status_code=502,
            detail="Together returned an invalid response.",
        ) from exc

    if not isinstance(reply, str) or not reply:
        raise HTTPException(
            status_code=502,
            detail="Together returned an empty response.",
        )

    return {
        "model": data.get("model", MODEL),
        "reply": reply,
        "usage": data.get("usage"),
    }

Check the finished code before you deploy it:

cd ts
npm run build
cd ..

python3 -m py_compile python/main.py

Step 3: Configure the Render service

Render can create the service from a Blueprint stored in render.yaml. Create that file in the repository root and use the version for your runtime.

services:
  - type: web
    name: together-chat
    runtime: node
    plan: free
    rootDir: ts
    buildCommand: npm ci && npm run build
    startCommand: npm start
    healthCheckPath: /health
    envVars:
      - key: TOGETHER_API_KEY
        sync: false
      - key: CHAT_API_KEY
        sync: false
      - key: TOGETHER_MODEL
        value: Qwen/Qwen3.5-9B

services:
  - type: web
    name: together-chat
    runtime: python
    plan: free
    rootDir: python
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn main:app --host 0.0.0.0 --port $PORT
    healthCheckPath: /health
    envVars:
      - key: TOGETHER_API_KEY
        sync: false
      - key: CHAT_API_KEY
        sync: false
      - key: TOGETHER_MODEL
        value: Qwen/Qwen3.5-9B
      - key: PYTHON_VERSION
        value: 3.14.3

Two Render settings matter here. The server binds to 0.0.0.0 so Render can route traffic to it, and it reads the PORT environment variable that Render provides. The sync: false setting tells Render to prompt for each secret during the initial Blueprint creation instead of storing it in Git. Render does not prompt for these values when it creates a Blueprint preview, so set preview secrets separately if you use preview environments.

Step 4: Deploy the Blueprint

Commit the project and push it to your Git provider:

Shell

git add .
git commit -m "Add Together AI chat service"
git branch -M main
git remote add origin YOUR_REPOSITORY_URL
git push -u origin main

Then create the service:

Open the Render Dashboard.
Select New, then Blueprint.
Connect the repository.
Enter your Together project API key for TOGETHER_API_KEY.
Enter the secret you generated earlier for CHAT_API_KEY.
Select Deploy Blueprint.

Render builds the selected runtime and assigns the service an HTTPS URL such as https://together-chat-xxxx.onrender.com. The service is ready when the deploy is live and the /health check passes.

A free Render web service spins down after 15 minutes without inbound traffic. Its next request can take about a minute while the service starts again. Use a paid instance if your application needs consistent response latency.

Step 5: Verify the deployment

Save the service URL in your shell:

Shell

export SERVICE_URL="https://together-chat-xxxx.onrender.com"

Check the health endpoint:

Shell

curl "$SERVICE_URL/health"

The response includes the configured model:

{
  "ok": true,
  "model": "Qwen/Qwen3.5-9B"
}

Confirm that the chat route rejects an unauthenticated request:

Shell

curl -i -X POST "$SERVICE_URL/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

The response has HTTP status 401. Next, load your CHAT_API_KEY without placing it in your shell history:

Shell

read -s CHAT_API_KEY
export CHAT_API_KEY

Send one authenticated inference request:

Shell

curl -X POST "$SERVICE_URL/chat" \
  -H "Authorization: Bearer $CHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"In one sentence, what is a vector database?"}'

A successful response has this shape:

{
  "model": "Qwen/Qwen3.5-9B",
  "reply": "A vector database stores and searches data as numerical vectors...",
  "usage": {
    "prompt_tokens": 17,
    "completion_tokens": 24,
    "total_tokens": 41
  }
}

The exact reply and token counts vary.

A non-empty reply confirms that the client authentication, Render service, Together API key, model ID, and network path all work.

Remove the shared secret from your shell when you finish:

Shell

unset CHAT_API_KEY

Change the model

The example uses Qwen3.5 9B. To use a different chat model:

Choose a model from the recommended models or the serverless model catalog.
Open the service in the Render Dashboard.
Change TOGETHER_MODEL under Environment.
Save the change and deploy the service.
Repeat the authenticated verification request.

Model availability, capabilities, and pricing change over time. Check the live catalog before changing the model string.

Extend the app

This guide sends one user message and waits for one complete response. These features require changes to the request schema and the handler:

Multi-turn chat: Accept and validate a messages array instead of a single message. See chat completions.
Streaming: Request stream: true and forward the returned stream to the client. The client must also parse streamed events.
Structured JSON: Add a supported response format and schema. See structured outputs.
Public access: Replace the shared bearer token with user authentication, and add rate limiting, usage monitoring, and abuse controls.

Next steps

Chat completions

Add multi-turn conversations and streaming to the handler.

Structured outputs

Enforce a JSON Schema on the model response.

Render web services

Review instance types, health checks, and scaling on Render.

Batch inference

Process many independent requests offline at lower cost.

GUIDES

MODEL QUICKSTARTS

BUILD APPS

BUILD AGENTS

WORK WITH CODING AGENTS

RAG & SEARCH

SDK INTEGRATIONS

DEDICATED CONTAINERS

Architecture

Prerequisites

Step 1: Create the project

Step 2: Add the chat handler

Step 3: Configure the Render service

Step 4: Deploy the Blueprint

Step 5: Verify the deployment

Change the model

Extend the app

Next steps

Chat completions

Structured outputs

Render web services

Batch inference

​Architecture

​Prerequisites

​Step 1: Create the project

​Step 2: Add the chat handler

​Step 3: Configure the Render service

​Step 4: Deploy the Blueprint

​Step 5: Verify the deployment

​Change the model

​Extend the app

​Next steps

Chat completions

Structured outputs

Render web services

Batch inference

Architecture

Prerequisites

Step 1: Create the project

Step 2: Add the chat handler

Step 3: Configure the Render service

Step 4: Deploy the Blueprint

Step 5: Verify the deployment

Change the model

Extend the app

Next steps