Building a Token-Metered AI Tool

What You’ll Build

An AI writing assistant: users enter a topic, and AI generates a draft article. Each call is billed based on actual token consumption — you just need an API Key, and the Profy SDK handles model calls and usage tracking. The end result:

Use the Profy SDK’s chat.completions.create to call AI models
Support both streaming and non-streaming modes
SDK automatically handles SSE parsing, error mapping, and timeouts
Token usage is returned in responses; the platform tracks it automatically

Calling Method Comparison

Dimension	SDK `chat.completions` (Recommended)	Direct HTTP	OpenAI SDK Compatible
Code Volume	Minimal — SDK wraps auth, parsing, errors	Most — manual SSE, errors	Medium — needs baseURL config
Auth	API Key auto-injected	Manual Authorization header	Pass apiKey
Error Handling	Typed exceptions	Manual status code parsing	OpenAI exception system
Streaming	`AsyncGenerator<ChatChunk>`	Manual SSE parsing	OpenAI Stream

This tutorial uses the Profy SDK’s chat.completions. If your scenario involves invoking published Experts (with persona + tools + memory), see Expert Invocation.

Prerequisites

Have a Profy developer account
Created an API Key (sk-pro- prefix) in the Platform Console
Installed the SDK: npm install @profy-ai/sdk or pip install profy-sdk

Step 1: Initialize the Client

import { Profy } from "@profy-ai/sdk";

const client = new Profy({
  apiKey: process.env.PROFY_API_KEY!,
});

from profy import Profy

client = Profy(api_key="sk-pro-...")

The API Key is a server-side credential — do not expose it in frontend code or Git repositories. Inject it via environment variables.

Step 2: Non-Streaming Call

const response = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [
    { role: "system", content: "You are a professional writing assistant." },
    { role: "user", content: "Write an article about future AI trends" },
  ],
  temperature: 0.7,
  maxTokens: 2000,
});

console.log(response.text);
console.log(`Tokens: ${response.usage.totalTokens}`);

async with Profy(api_key="sk-pro-...") as client:
    response = await client.chat.completions.create(
        model="deepseek-chat",
        messages=[
            {"role": "system", "content": "You are a professional writing assistant."},
            {"role": "user", "content": "Write an article about future AI trends"},
        ],
        temperature=0.7,
        max_tokens=2000,
    )

    print(response.text)
    print(f"Tokens: {response.usage.total_tokens}")

Key fields in ChatResponse:

Field	Type	Description
`text`	`string`	Complete generated text
`usage.promptTokens`	`number`	Input token count
`usage.completionTokens`	`number`	Output token count
`usage.totalTokens`	`number`	Total token count
`model`	`string`	Model actually used

Step 3: Streaming Call

Set stream: true for real-time streaming output, ideal for typewriter-style chat interfaces.

const stream = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [
    { role: "system", content: "You are a professional writing assistant." },
    { role: "user", content: "Write an article about AI" },
  ],
  stream: true,
  temperature: 0.7,
  maxTokens: 2000,
});

for await (const chunk of stream) {
  if (chunk.text) {
    process.stdout.write(chunk.text);
  }
}

async with Profy(api_key="sk-pro-...") as client:
    stream = await client.chat.completions.create(
        model="deepseek-chat",
        messages=[
            {"role": "system", "content": "You are a professional writing assistant."},
            {"role": "user", "content": "Write an article about AI"},
        ],
        stream=True,
        temperature=0.7,
        max_tokens=2000,
    )

    async for chunk in stream:
        if chunk.text:
            print(chunk.text, end="", flush=True)

Step 4: Error Handling

The SDK throws typed exceptions based on HTTP status codes:

Exception	HTTP Status	Meaning	Handling
`InvalidRequestError`	400	Invalid request parameters or model unavailable	Check `model` name and request body
`AuthenticationError`	401	Invalid API Key	Verify Key configuration
`InsufficientBalanceError`	402	Insufficient balance	Prompt to top up, do not retry
`RateLimitError`	429	Too many requests	Exponential backoff retry

import {
  Profy,
  InsufficientBalanceError,
  RateLimitError,
  InvalidRequestError,
} from "@profy-ai/sdk";

async function chatWithRetry(
  client: Profy,
  messages: Array<{ role: string; content: string }>,
  maxRetries = 3,
) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({
        model: "deepseek-chat",
        messages,
      });
    } catch (err) {
      if (err instanceof InsufficientBalanceError) {
        throw new Error("Insufficient balance — please top up");
      }
      if (err instanceof RateLimitError && attempt < maxRetries) {
        const delay = Math.min(1000 * 2 ** attempt, 10_000);
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      if (err instanceof InvalidRequestError) {
        throw new Error(`Invalid request: ${err.message}`);
      }
      throw err;
    }
  }
}

import asyncio
from profy import (
    Profy,
    InsufficientBalanceError,
    RateLimitError,
    InvalidRequestError,
)

async def chat_with_retry(
    client: Profy,
    messages: list[dict],
    max_retries: int = 3,
):
    for attempt in range(max_retries + 1):
        try:
            return await client.chat.completions.create(
                model="deepseek-chat",
                messages=messages,
            )
        except InsufficientBalanceError:
            raise ValueError("Insufficient balance — please top up")
        except RateLimitError:
            if attempt < max_retries:
                delay = min(1.0 * 2**attempt, 10.0)
                await asyncio.sleep(delay)
                continue
            raise
        except InvalidRequestError as e:
            raise ValueError(f"Invalid request: {e}") from e

Do not retry on InsufficientBalanceError (402) — insufficient balance won’t change with retries. Show a top-up prompt instead.

Step 5: Query Available Models

const models = await client.models.list();
for (const model of models) {
  console.log(`${model.id} — ${model.owned_by}`);
}

models = await client.models.list()
for model in models:
    print(f"{model['id']} — {model.get('owned_by', 'unknown')}")

The available model list depends on the platform administrator’s configuration. Common models include deepseek-chat, deepseek-reasoner, qwen-plus, etc.

Complete Example

An AI writing assistant backend with streaming and error handling.

import express from "express";
import { Profy, InsufficientBalanceError } from "@profy-ai/sdk";

const app = express();
app.use(express.json());

const client = new Profy({ apiKey: process.env.PROFY_API_KEY! });

app.post("/api/chat", async (req, res) => {
  try {
    const stream = await client.chat.completions.create({
      model: "deepseek-chat",
      messages: [
        { role: "system", content: "You are a professional writing assistant." },
        ...req.body.messages,
      ],
      stream: true,
      temperature: 0.7,
      maxTokens: 2000,
    });

    res.setHeader("Content-Type", "text/event-stream");
    res.setHeader("Cache-Control", "no-cache");

    for await (const chunk of stream) {
      if (chunk.text) {
        res.write(`data: ${JSON.stringify({ content: chunk.text })}\n\n`);
      }
    }

    res.write("data: [DONE]\n\n");
    res.end();
  } catch (err) {
    if (err instanceof InsufficientBalanceError) {
      return res.status(402).json({ error: "Insufficient credits. Please top up." });
    }
    return res.status(500).json({ error: String(err) });
  }
});

app.listen(3000);

import json
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from profy import Profy, InsufficientBalanceError

app = FastAPI()
client = Profy(api_key="sk-pro-...")

class ChatRequest(BaseModel):
    message: str

@app.post("/api/chat")
async def chat(body: ChatRequest):
    async def stream_response():
        try:
            stream = await client.chat.completions.create(
                model="deepseek-chat",
                messages=[
                    {"role": "system", "content": "You are a professional writing assistant."},
                    {"role": "user", "content": body.message},
                ],
                stream=True,
                temperature=0.7,
                max_tokens=2000,
            )
            async for chunk in stream:
                if chunk.text:
                    yield f"data: {json.dumps({'content': chunk.text})}\n\n"
            yield "data: [DONE]\n\n"
        except InsufficientBalanceError:
            yield f"data: {json.dumps({'error': 'Insufficient credits. Please top up.'})}\n\n"

    return StreamingResponse(stream_response(), media_type="text/event-stream")

OpenAI SDK Compatibility (Alternative)

Profy’s /v1/chat/completions endpoint is OpenAI-compatible, so you can use the official OpenAI SDK directly:

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.PROFY_API_KEY!,
  baseURL: "https://api.profy.cn/v1",
});

const completion = await openai.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "Write a product description" }],
});

console.log(completion.choices[0].message.content);

from openai import AsyncOpenAI

openai_client = AsyncOpenAI(
    api_key="sk-pro-...",
    base_url="https://api.profy.cn/v1",
)

completion = await openai_client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Write a product description"}],
)

print(completion.choices[0].message.content)

We recommend using the Profy SDK — it provides typed exceptions, Expert invocation, and other Profy-specific features. The OpenAI SDK approach is ideal for projects migrating from OpenAI.

Next Steps

Per-Use Billing

Implement per-call billing with ProfyApp reportEvent

Expert Invocation

Invoke published AI Experts on the platform

Next.js Full-Stack Integration

Complete OAuth + billing + AI call full-stack application

SDK Quick Start

Install SDK, create API Key, first call

Get Started

Authentication & Keys

API Guides

SDK

Integrations

Cookbook

Reference

Building a Token-Metered AI Tool

What You’ll Build

Calling Method Comparison

Prerequisites

Step 1: Initialize the Client

Step 2: Non-Streaming Call

Step 3: Streaming Call

Step 4: Error Handling

Step 5: Query Available Models

Complete Example

OpenAI SDK Compatibility (Alternative)

Next Steps

Per-Use Billing

Expert Invocation

Next.js Full-Stack Integration

SDK Quick Start

​What You’ll Build

​Calling Method Comparison

​Prerequisites

​Step 1: Initialize the Client

​Step 2: Non-Streaming Call

​Step 3: Streaming Call

​Step 4: Error Handling

​Step 5: Query Available Models

​Complete Example

​OpenAI SDK Compatibility (Alternative)

​Next Steps

Per-Use Billing

Expert Invocation

Next.js Full-Stack Integration

SDK Quick Start

What You’ll Build

Calling Method Comparison

Prerequisites

Step 1: Initialize the Client

Step 2: Non-Streaming Call

Step 3: Streaming Call

Step 4: Error Handling

Step 5: Query Available Models

Complete Example

OpenAI SDK Compatibility (Alternative)

Next Steps