DeepSeek on the Aggregator: From API Key to First Successful Response

Why DeepSeek on an OpenAI-Compatible Endpoint

DeepSeek models are accessible through the same chat completions interface you may already use for other providers. If you have an OpenAI-compatible client, you can point it at the aggregator's base URL and start sending requests with minimal changes.

This guide walks through the first call: choosing the model string, shaping the payload, and interpreting the response so you can tell success from failure.

Prerequisites

• An API key from the aggregator
• A tool or library that supports OpenAI-compatible chat completions (curl, Python openai package, Node openai package, etc.)
• A funded account balance (USDC on Base), since calls are pay-as-you-go

Step 1: Identify the Correct Model String

Model strings are exact identifiers. For DeepSeek, they typically follow a pattern like deepseek-chat or deepseek-reasoner, but the authoritative list is always in the aggregator's model catalog.

• Do not guess. Check the docs or the /models endpoint for the exact string.
• Case matters. DeepSeek-Chat and deepseek-chat may not be treated the same.
• If you are unsure, start with the general chat model before trying specialized variants.

Step 2: Build the Payload

The aggregator accepts an OpenAI-compatible JSON body. A minimal request looks like this:

{
  "model": "deepseek-chat",
  "messages": [
    { "role": "user", "content": "Explain what an API aggregator does in one sentence." }
  ]
}

Key fields:

• model: The exact DeepSeek model string from Step 1.
• messages: An array of conversation turns. For a first call, a single user message is enough.
• stream: Optional. Set to true if you want server-sent events instead of a single JSON response.
• max_tokens: Optional. Caps the length of the reply. If omitted, the model uses its default.
• temperature: Optional. Controls randomness. For factual answers, a lower value is often used.

DeepSeek models may support additional parameters such as topp, frequencypenalty, or presence_penalty. These map directly onto the OpenAI-compatible schema. If a parameter is not supported, the API will usually return an error rather than ignore it silently.

Step 3: Send the Request

Using curl:

curl https://api.aggregator.example/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Say hello."}]
  }'

Using Python:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.aggregator.example/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Say hello."}]
)

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

The base URL and model string must match the aggregator's documentation. If you see a 404, the model string is likely wrong. A 401 points to an authentication issue. A 402 or similar may indicate insufficient balance.

Step 4: Read a Normal Response

A successful non-streaming response looks like this:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

What to check:

• choices[0].message.content contains the model's reply.
• finishreason is stop for a complete answer. Other values like length mean the output was cut off by maxtokens.
• usage shows token counts, which determine your cost. The aggregator bills at official price × 1.3 for users.
• model echoes the model string you requested, which helps confirm routing.

Step 5: Recognize a Broken Response

Common failure shapes:

• Error object: {"error": {"message": "...", "type": "..."}}. Read the message. It usually names the invalid field.
• Empty content: content is null or an empty string. This can happen if the model was filtered or if the request was malformed.
• Truncated output: finishreason is length and the text stops mid-sentence. Increase maxtokens or shorten the prompt.
• Wrong model echoed: If model in the response differs from what you sent, the aggregator may have routed to a fallback. Check your model string.
• Unexpected role: The response should have role: assistant. If not, you may be parsing the wrong object.

Streaming Responses

If you set stream: true, the response is a series of server-sent events. Each event contains a delta with a piece of the content. The final event has finish_reason set and no content. Your client must accumulate the deltas to reconstruct the full message.

A normal stream ends with data: [DONE]. If the stream stops without that marker, the connection may have dropped.

Cost and Contribution Model

You pay the official DeepSeek price multiplied by 1.3 in USDC. There is no KYC required to top up. If you contribute keys or capacity, you are credited at official price × 1.1 (or × 1.2 for premium contributions) in USDC. This is not a discount on your own usage; it is a separate contributor credit.

Next Steps

• Try a multi-turn conversation by adding more messages to the array.
• Experiment with temperature and max_tokens to see how they affect output.
• Check the aggregator's model catalog for other DeepSeek variants and their exact strings.
• Use the usage field to monitor token consumption and cost.