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 Top Up Your Balance

Navigate to Billing in the dashboard sidebar. Choose a top-up amount and complete the payment. Your balance updates instantly 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 New Key, give it a descriptive name (e.g. “My Development Key”), select the key type that matches the models you intend to use, and click Create. 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 server is reachable. Hit the health-check endpoint:

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

A successful response returns a 200 OK status with a JSON body confirming the service is healthy. If you receive a 401 Unauthorized, double-check that your API key is correct and prefixed with Bearer (note the trailing space). A 403 Forbidden indicates your key type does not have permission — verify the key type in the dashboard.

Expected Response

{
  "status": "ok",
  "service": "ai-api-proxy",
  "version": "1.0.0"
}

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.

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-4o)
• context_window — maximum tokens the model accepts (input + output)
• pricing — cost per input and output token in your account's currency
• supported_modalities — capabilities such as text, image input, function calling, or streaming

Example Response (abbreviated)

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "context_window": 128000,
      "pricing": { "input": 0.0025, "output": 0.01 },
      "supported_modalities": ["text", "image", "function_calling"]
    },
    {
      "id": "claude-sonnet-4-6",
      "object": "model",
      "context_window": 200000,
      "pricing": { "input": 0.003, "output": 0.015 },
      "supported_modalities": ["text", "image"]
    }
  ]
}

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-4o",
    "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-4o",
  "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-4o",
    "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": "claude-sonnet-4-6",
    "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": "claude-sonnet-4-6",
    "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": "claude-sonnet-4-6",
  "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 the AI API Proxy. 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 pricing page for per-model token rates and estimated costs for common use cases. 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.