How to Use find-token

Quick Start

Get from zero to your first API response in under 5 minutes.

API Key Usage

API keys are your credential for accessing find-token's API. They are managed from your dashboard.

Key Format

All find-token API keys follow this format:

sk-ft_<64-character-hex-string>

A full key looks like: sk-ft_a1b2c3d4e5f6... (68 characters total).

How to Use Your Key

Include the key in every API request via the HTTP Authorization header:

Authorization: Bearer sk-ft_<your-key>

Key Security Best Practices

• Never expose your key in client-side code, version control, or public repositories
• Use environment variables to store keys: export FINDTOKEN_API_KEY="sk-ft_..."
• Rotate keys regularly by creating a new key, updating your applications, then revoking the old one
• Use separate keys for development and production environments
• Revoke compromised keys immediately from your dashboard

Creating Multiple Keys

You can create multiple API keys at any time. All keys share the same account balance and usage limits. This is useful for segmenting access by application or environment.

Revoking a Key

Revoking a key immediately invalidates it. Any application using a revoked key will receive 401 Unauthorized responses. Revoked keys cannot be re-enabled.

Code Examples

find-token is fully compatible with the OpenAI SDK. The only change needed is the base URL and your API key.

# pip install openai
from openai import OpenAI

# Set your API key as an environment variable:
# export FINDTOKEN_API_KEY="sk-ft_your-key-here"

client = OpenAI(
    base_url="https://api.find-token.com/v1",
    api_key="sk-ft_your-key-here",
)

# Non-streaming request
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ],
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
    baseURL: "https://api.find-token.com/v1",
    apiKey: "sk-ft_your-key-here",
});

// Non-streaming request
const response = await client.chat.completions.create({
    model: "deepseek-chat",
    messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is the capital of France?" },
    ],
});

console.log(response.choices[0].message.content);
console.log(`Tokens used: ${response.usage.total_tokens}`);

curl https://api.find-token.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ft_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Available Models

You can list all available models via the API:

curl https://api.find-token.com/v1/models \
  -H "Authorization: Bearer sk-ft_your-key-here"

Or visit the Pricing section on the home page for the full list of models and their costs.

Standard Mode (Prepaid Credits)

Standard mode is the simplest way to use find-token. You prepay via Stripe, and each API call deducts from your balance.

How It Works

1. Recharge: Add funds to your account via Stripe (credit/debit card). Minimum recharge is $10.
2. Fee: A 5.5% gateway fee is applied to each recharge. Recharge $10, receive $9.45 in credits.
3. Use: Make API calls as needed. Each call deducts the actual cost from your balance.
4. Monitor: Check your balance and billing logs from the dashboard in real time.

Recharge via API

curl https://api.find-token.com/v1/user/credits \
  -H "Authorization: Bearer sk-ft_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20.00,
    "success_url": "https://www.find-token.com/my/dashboard",
    "cancel_url": "https://www.find-token.com/my/pricing"
  }'

The response includes a checkout_url. Redirect the user to Stripe's hosted checkout page to complete payment.

Check Balance

curl https://api.find-token.com/v1/user/balance \
  -H "Authorization: Bearer sk-ft_your-key-here"

BYOK Mode (Bring Your Own Key)

BYOK mode is ideal for high-volume users who already have provider API keys (DeepSeek, Zhipu, etc.). You bring your own key, and find-token handles the routing and response formatting.

How It Works

• Register your key: Save your provider API key securely with find-token (AES-256-GCM encrypted).
• Free tier: The first 1,000,000 requests per month are free across all models.
• Beyond free tier: A 5% routing fee applies to requests beyond 1M/month.
• Counter resets: On the 1st of each month at 00:00 UTC.

Register a Provider Key

curl https://api.find-token.com/v1/user/byok/register \
  -H "Authorization: Bearer sk-ft_your-findtoken-key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "deepseek",
    "api_key": "sk-your-deepseek-api-key",
    "name": "My DeepSeek Account"
  }'

List Registered Keys

curl https://api.find-token.com/v1/user/byok/keys \
  -H "Authorization: Bearer sk-ft_your-findtoken-key"

Use BYOK in a Request

You can either rely on a pre-registered key (auto-matched by provider name) or pass the key inline:

curl https://api.find-token.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ft_your-findtoken-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}],
    "provider_key": {
      "provider": "deepseek",
      "api_key": "sk-your-deepseek-key-here"
    }
  }'

Supported Providers for BYOK

Streaming (SSE)

find-token supports Server-Sent Events (SSE) streaming, compatible with OpenAI's streaming format. Streaming is ideal for chatbot applications where you want to show responses token by token.

How to Enable Streaming

Set "stream": true in your request body. The API will return a stream of events instead of a single JSON response.

curl https://api.find-token.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ft_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Count from 1 to 5."}],
    "stream": true
  }'

Streaming with Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.find-token.com/v1",
    api_key="sk-ft_your-key-here",
)

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Write a short poem."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Streaming with JavaScript

const response = await client.chat.completions.create({
    model: "deepseek-chat",
    messages: [{ role: "user", content: "Write a short poem." }],
    stream: true,
});

for await (const chunk of response) {
    process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Streaming Response Format

Each SSE event looks like this:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1715212345,"model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1715212345,"model":"deepseek-chat","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: [DONE]

The stream ends with data: [DONE]. Some providers (Zhipu, MiniMax) simulate streaming by returning the full response as a single chunk for compatibility.

Smart Routing

find-token automatically routes your requests to the best available provider. You can control the routing strategy using the routing parameter.

Routing Strategies

Example: Using cheapest routing

curl https://api.find-token.com/v1/chat/completions \
  -H "Authorization: Bearer sk-ft_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}],
    "routing": "cheapest"
  }'

Model Equivalence Groups

The routing system groups equivalent models so that if one provider is down, your request can be served by an alternative. For example:

• deepseek-chat can route to qwen-max, glm-4-plus, kimi-k2, or minimax-m2.5
• deepseek-coder can route to qwen-turbo or glm-4-flash

This means even if your preferred model is temporarily unavailable, your application continues to work seamlessly.

Billing & Usage Monitoring

Track your spending and usage in real time through the dashboard or API.

Response Headers

Every API response includes billing information in custom headers:

View Billing Logs

All API calls are recorded in your billing logs with model, token counts, and cost:

curl https://api.find-token.com/v1/user/billing-logs \
  -H "Authorization: Bearer sk-ft_your-key-here"

View Recharge History

curl https://api.find-token.com/v1/user/recharges \
  -H "Authorization: Bearer sk-ft_your-key-here"

Understanding Your Costs

Cost is calculated per request based on token usage and the model's price:

• Standard mode: provider_cost x (1 + 5.5%). For example, deepseek-chat at $0.14/M input tokens + 5.5% = $0.1477/M.
• BYOK mode: Free for the first 1M requests/month, then provider_cost x 5% for routing.

All costs are calculated with 8 decimal places of precision and rounded to 6 decimal places for display.

Best Practices

Optimize for Cost

• Use BYOK mode if you already have provider API keys or expect high volume (the free tier covers up to 1M requests/month)
• Use routing: "cheapest" for batch jobs where latency isn't critical but cost is
• Choose flash models for simple tasks: glm-4-flash ($0.10/M input) vs glm-4-plus ($0.50/M input)
• Monitor billing logs regularly to detect unexpected usage patterns

Optimize for Reliability

• Use routing: "fallback" for production applications where uptime is critical
• Implement exponential backoff in your application for handling 429 (rate limit) and 503 (provider unavailable) responses
• Set reasonable max_tokens to prevent runaway costs from unexpectedly long responses

Error Handling

All errors follow a consistent JSON format. Key error codes:

Frequently Asked Questions