Quick Start Guide

1. Get Your API Key

An API key authenticates every request you send. Before you can create one you need an account with a funded balance.

1.1 Register an Account

Visit the registration page and create an account with your email address. You will receive a verification link — click it to activate your account, then log in to the dashboard.

1.2 Buy Credits

Navigate to Buy Credits in the dashboard sidebar. Choose an amount (the minimum top-up is $1.50) and complete the payment. Your balance updates once the payment is confirmed and you can start making API calls right away. Every request deducts credits based on the model's per-token pricing.

1.3 Create an API Key

Go to the API Keys section of the dashboard, click Create Key, and choose the key type that matches the models you intend to call: a Standard key covers every model in the catalog except jzs-max-3.0, which needs its own dedicated key. Keys have no name field — identify them by their prefix and creation date. Copy the generated key immediately — it will only be shown once.

2. Base URLs

All API endpoints are relative to a single base URL. The base URL acts as the root for every request you make — append the desired endpoint path to it.

Available Base URL

Every endpoint documented below is relative to this base URL. For example, the models endpoint becomes https://jzstoken.com/api/v1/models. If you are running your own instance, substitute the host and port accordingly.

3. Test Your Connection

Before diving into model calls, verify that your API key works and the endpoint is reachable. List the models your key can call:

curl https://jzstoken.com/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

A valid key returns 200 OK and only the models that key can actually call — a Standard key lists everything except jzs-max-3.0, and a key made for jzs-max-3.0 lists just that one. 401 Unauthorized means the key is missing or wrong — check that the header reads Bearer YOUR_API_KEY with a single space after Bearer. 402 Payment Required means the balance is too low for the model. 403 Forbidden means the key type does not cover the model you asked for.

Expected Response

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-terra",
      "object": "model",
      "created": 1756300000,
      "owned_by": "llm-proxy"
    }
  ]
}

4. List All Available Models

The /v1/models endpoint returns every model your API key can access, along with metadata like context window size and per-token pricing. This is the best way to discover which models are available before sending a chat completion. For the current provider-grouped prices, see the live model pricing page.

curl https://jzstoken.com/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is a JSON object with a data array. Each entry contains:

• id — the model identifier you'll use in requests (e.g. gpt-5.6-terra)
• context_window — maximum tokens the model accepts (input + output)
• pricing — the response's pricing fields for input and output usage; see the live model pricing page for current rates
• supported_modalities — capabilities such as text, image input, function calling, or streaming

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-terra",
      "object": "model",
      "created": 1756300000,
      "owned_by": "llm-proxy"
    },
    {
      "id": "jzs-max-3.0",
      "object": "model",
      "created": 1756300000,
      "owned_by": "llm-proxy"
    }
  ]
}

5. Your First Chat Completion

The /v1/chat/completions endpoint is the primary way to interact with language models. It follows the OpenAI-compatible schema, so any library or tool that speaks the OpenAI Chat Completions API will work with our proxy.

Non-Streaming Request

Send a single-turn chat completion and receive the full response in one JSON payload:

curl https://jzstoken.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain how API proxies work in two sentences."}
    ],
    "temperature": 0.7,
    "max_tokens": 200
  }'

Request Fields Explained

• model — the model ID from the /v1/models response (required).
• messages — an ordered array of conversation turns. Each message has a role (system, user, or assistant) and content (required).
• temperature — controls randomness (0–2). Lower values produce more deterministic output; higher values increase creativity (optional, defaults to 1).
• max_tokens — caps the number of tokens the model can generate in its response (optional but recommended).

Example Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An API proxy acts as an intermediary that forwards your requests to upstream AI providers, handling authentication, rate-limiting, and billing so you only need one key. It also unifies different provider formats into a single, consistent schema, simplifying integration."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 35,
    "completion_tokens": 54,
    "total_tokens": 89
  }
}

The usage block tells you exactly how many tokens were consumed. The finish_reason field indicates why the model stopped: stop means it finished naturally, length means it hit the max_tokens limit, and content_filter means the response was blocked by a safety filter.

6. Streaming Chat Completion

For a more responsive user experience, set stream: true in your request body. The server delivers tokens as they are generated using Server-Sent Events (SSE), so your UI can display output incrementally instead of waiting for the full response.

curl https://jzstoken.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.6-terra",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Write a haiku about programming."}
    ],
    "temperature": 0.9,
    "max_tokens": 100
  }'

What the Stream Looks Like

Each chunk is delivered as a data: line containing a JSON object with a choices array. The delta contains the new token under delta.content. The stream terminates with data: [DONE].

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"A"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" screen"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" glows"},"finish_reason":null}]}

data: [DONE]

Note that the first chunk often contains an empty content field — it signals the assistant role. Subsequent chunks carry the actual tokens. To consume the stream programmatically, read the response body line by line, skip empty lines, strip the data: prefix, parse the remainder as JSON, and stop when you encounter [DONE].

7. Messages API (Claude-Compatible)

In addition to the OpenAI-compatible chat completions endpoint, the proxy also exposes a Messages API at /v1/messages that mirrors the Anthropic Messages schema. This is useful when you are migrating from the Anthropic API or using tools that speak the Anthropic format natively — no adapter layer required.

Basic Messages Request

curl https://jzstoken.com/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "jzs-max-3.0",
    "max_tokens": 300,
    "system": "You are a world-class poet. Respond only in verse.",
    "messages": [
      {"role": "user", "content": "Describe the ocean at dawn."}
    ]
  }'

Key Differences from Chat Completions

• System prompt is a top-level system field, not a message with role: "system".
• Message roles are limited to user and assistant (no system role inside the messages array).
• Header requirement: you must include anthropic-version (e.g. 2023-06-01).
• Response shape uses content blocks (an array of text blocks) instead of a flat choices structure.

Messages Streaming

The Messages API also supports streaming. Set stream: true in the JSON body (not a header). The server delivers SSE events with event: types such as message_start, content_block_delta, and message_stop:

curl https://jzstoken.com/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "jzs-max-3.0",
    "max_tokens": 200,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from 1 to 5 slowly."}
    ]
  }'

Example Messages Response (non-streaming)

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "jzs-max-3.0",
  "content": [
    {
      "type": "text",
      "text": "First light spills over the horizon's rim,\nTurning black waves to sheets of hammered gold.\nGulls wake and wheel above the breathing deep,\nWhile silence shatters into morning's hymn."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 25,
    "output_tokens": 52
  }
}

8. Next Steps

You now have a working connection to JZS Token. Here is where to go from here:

• API Reference — browse the full endpoint documentation for /v1/chat/completions, /v1/messages, /v1/embeddings, /v1/images/generations, and more. Every parameter, response field, and error code is covered.
• Client Guides — step-by-step tutorials for connecting popular tools: Cursor, Claude Code, Chatbox, Cherry Studio, and more.
• Pricing — see the live model pricing page for current per-model token and per-image rates. The API response example above is illustrative; all pricing is pay-as-you-go with no monthly minimums.
• SDK Integration — use our OpenAI-compatible endpoints directly with the official openai Python or Node.js SDKs by setting the baseURL parameter. Same for the Anthropic SDKs with the Messages endpoint.
• Usage Dashboard — monitor your token consumption, set spending alerts, and review request logs from the dashboard to keep costs under control.