> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Messages API 申请及使用

> Claude AI 集成指南 - XHuoAPI

Anthropic Claude to bardzo potężny system AI do rozmów, który po wprowadzeniu podpowiedzi potrafi w ciągu kilku sekund wygenerować płynne i naturalne odpowiedzi. Claude Messages API to oficjalny natywny format API Anthropic, który różni się od formatu zgodnego z OpenAI (Chat Completion), przyjmuje własną strukturę żądań i odpowiedzi, co pozwala lepiej wykorzystać unikalne możliwości Claude'a, takie jak wejście treści multimodalnych, wywołania narzędzi, głębokie myślenie (Extended Thinking) i inne zaawansowane cechy.

Dokument ten głównie opisuje proces korzystania z Claude Messages API, dzięki któremu możemy korzystać z natywnego interfejsu zgodnego z oficjalnym Anthropic do wywoływania funkcji rozmowy Claude'a.

## Proces aplikacji

Aby korzystać z Claude Messages API, najpierw można przejść na stronę [Claude Messages API](https://api.xhuoapi.ai/documents/280928a2-2dce-419c-adb5-1ea835e8183a) i kliknąć przycisk „Acquire”, aby uzyskać potrzebne poświadczenia do żądania:

![](https://cdn.xhuoapi.ai/nyq0xz.png)

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zalogowaniu lub rejestracji automatycznie wrócisz na bieżącą stronę.

Podczas pierwszej aplikacji przyznawana jest darmowa pula, dzięki czemu można korzystać z tego API bezpłatnie.

## Podstawowe użycie

Ścieżka żądania Claude Messages API to `/v1/messages`, zgodna z oficjalnym API Anthropic. Musimy podać co najmniej trzy obowiązkowe parametry:

* `model`: wybór modelu Claude, np. `claude-opus-4-20250514`, `claude-sonnet-4-20250514` itp.
* `messages`: tablica wiadomości wejściowych, każda wiadomość zawiera `role` (rola) i `content` (treść), gdzie `role` obsługuje `user` i `assistant`.
* `max_tokens`: maksymalna liczba tokenów wyjściowych, używana do ograniczenia długości pojedynczej odpowiedzi.

Często używane opcjonalne parametry:

* `system`: podpowiedź systemowa, używana do ustalenia zachowania i roli modelu.
* `temperature`: losowość generacji, w zakresie 0-1, im wyższa wartość, tym bardziej rozproszone odpowiedzi.
* `stream`: czy używać odpowiedzi strumieniowej, ustawienie na `true` umożliwia zwracanie wyników słowo po słowie.
* `stop_sequences`: niestandardowe sekwencje zatrzymania, model przestanie generować, gdy napotka te teksty.
* `top_p`: parametr próbkowania jądra, współpracujący z temperaturą w kontrolowaniu losowości generacji.
* `top_k`: próbkowanie tylko z K najwyżej prawdopodobnych opcji.
* `tools`: definicja narzędzi, umożliwiająca modelowi wywoływanie zewnętrznych funkcji.
* `tool_choice`: kontroluje, jak model korzysta z dostarczonych narzędzi.

### Przykład cURL

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'
```

### Przykład w Pythonie

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Po wywołaniu, zwrócony wynik wygląda następująco:

```json theme={null}
{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}
```

Opis pól zwróconego wyniku:

* `id`: unikalny identyfikator tej wiadomości.
* `type`: zawsze `message`.
* `role`: zawsze `assistant`.
* `content`: tablica treści odpowiedzi, każdy element zawiera `type` (np. `text`) i odpowiadającą treść.
* `model`: nazwa modelu przetwarzającego żądanie.
* `stop_reason`: powód zatrzymania, możliwe wartości to `end_turn` (normalne zakończenie), `max_tokens` (osiągnięcie maksymalnej długości), `stop_sequence` (napotkanie sekwencji zatrzymania), `tool_use` (wywołanie narzędzia).
* `stop_sequence`: jeśli zatrzymano z powodu niestandardowej sekwencji zatrzymania, wyświetla dopasowany tekst sekwencji zatrzymania.
* `usage`: statystyki użycia tokenów, zawierające `input_tokens` (liczba tokenów wejściowych) i `output_tokens` (liczba tokenów wyjściowych).

## Systemowe podpowiedzi

Claude Messages API obsługuje ustawianie systemowych podpowiedzi za pomocą pola `system`, które służy do definiowania zachowania, roli i kontekstu modelu.

### Przykład w Pythonie

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "Jesteś profesjonalnym asystentem tłumaczeń chińskich, przetłumacz angielskie zdania wprowadzone przez użytkownika na chiński.",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Ustawiając podpowiedź `system`, można precyzyjnie kontrolować rolę i sposób działania Claude'a.

## Odpowiedzi strumieniowe

Interfejs ten obsługuje również odpowiedzi strumieniowe, ustawiając parametr `stream` na `true`, aby uzyskać efekt stopniowego zwracania, co jest bardzo odpowiednie do implementacji wyświetlania słowo po słowie na stronie internetowej.

### Przykład w Pythonie

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))
```

Odpowiedzi strumieniowe są zwracane w formacie Server-Sent Events (SSE), każda linia zaczyna się od `event:` i `data:`. Typy zdarzeń strumieniowych obejmują:

* `message_start`: początek wiadomości, zawierający podstawowe informacje o wiadomości i nazwę modelu.
* `content_block_start`: początek bloku treści.
* `content_block_delta`: inkrementalne aktualizacje bloku treści, zawierające nowo wygenerowane fragmenty tekstu.
* `content_block_stop`: koniec bloku treści.
* `message_delta`: inkrementalne aktualizacje na poziomie wiadomości, zawierające `stop_reason` i ostateczne informacje o `usage`.
* `message_stop`: koniec wiadomości.

Efekt wyjściowy wygląda następująco:

```
event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Cześć"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! Mam na imię"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. Jak mogę ci dzisiaj pomóc?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}
```

Można zauważyć, że zdarzenia `content_block_delta` w odpowiedzi strumieniowej zawierają stopniowo generowaną treść tekstową, a po połączeniu wszystkich `text_delta` można uzyskać pełną odpowiedź.

### Przykład JavaScript

```javascript theme={null}
const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Cześć, Claude" }],
  }),
};

const response = await fetch("https://api.xhuoapi.ai/v1/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}
```

## Wiele rund rozmowy

Jeśli chcesz zintegrować funkcję wielu rund rozmowy, musisz na przemian umieszczać wiadomości ról `user` i `assistant` w tablicy `messages`, przekazując również wcześniejszą historię rozmowy.

### Przykład Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Cześć, mam na imię Alice."},
        {"role": "assistant", "content": "Cześć Alice! Miło cię poznać. Jak mogę ci dzisiaj pomóc?"},
        {"role": "user", "content": "Jakie jest moje imię?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Wynik zwrócony:

```json theme={null}
{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Twoje imię to Alice, jak właśnie mi powiedziałaś!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}
```

Przekazując pełną historię rozmowy w `messages`, Claude może dokładnie odpowiadać, uwzględniając kontekst.

## Model głębokiego myślenia

Claude wspiera funkcję Extended Thinking (głębokie myślenie), która pozwala modelowi na wewnętrzne rozumowanie przed udzieleniem odpowiedzi, zwiększając dokładność w rozwiązywaniu złożonych problemów. Aby skorzystać z tej funkcji, należy przekazać parametr `thinking`.

### Przykład Python

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Jaki jest sinus 30 stopni? Pokaż swoje rozumowanie."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Wynik zwrócony:

```json theme={null}
{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "Użytkownik pyta o sinus 30 stopni. To podstawowe pytanie z trygonometrii.\n\nW trójkącie 30-60-90 boki są w proporcji 1:√3:2.\n\nDla kąta 30°:\n- Bok przeciwny ma długość 1\n- Przeciwprostokątna ma długość 2\n- Więc sin(30°) = przeciwny/przeciwprostokątna = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "Sinus 30 stopni to **1/2** lub **0.5**.\n\nTo jedna z podstawowych wartości trygonometrycznych. W trójkącie 30-60-90 boki są w proporcji 1:√3:2, gdzie bok przeciwny kątowi 30° ma długość 1, a przeciwprostokątna ma długość 2, co daje nam sin(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}
```

Można zauważyć, że tablica `content` zawiera dwa bloki treści:

* `type: "thinking"`: wewnętrzny proces myślenia modelu, pokazujący kroki rozumowania.
* `type: "text"`: ostateczny wynik odpowiedzi.

Uwagi:

* Używając `thinking`, `max_tokens` musi być większe niż `budget_tokens`, ponieważ `budget_tokens` to budżet tokenów przeznaczony na proces myślenia.
* Im większy `budget_tokens`, tym większa przestrzeń dla modelu na głębsze rozumowanie, co jest odpowiednie do rozwiązywania złożonych problemów.

## Model wizualny

Claude wspiera wejścia multimodalne, mogąc jednocześnie przetwarzać tekst i obrazy. W API Messages można użyć zdolności wizualnych, ustawiając `content` jako format tablicy i przekazując bloki treści obrazu.

### Użycie obrazu zakodowanego w Base64

```python theme={null}
import base64
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# Odczyt i kodowanie obrazu
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "Co jest na tym obrazie?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Użycie obrazu z URL

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.xhuoapi.ai/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Co jest na tym obrazku?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### cURL przykład

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.xhuoapi.ai/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "Co'\'' jest na tym obrazku?"
          }
        ]
      }
    ]
  }'
```

Obsługiwane formaty obrazów to: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.

Przykład odpowiedzi:

```json theme={null}
{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ten obrazek pokazuje interfejs konfiguracji żądania API dla tego, co wydaje się być usługą zakończenia czatu AI. Interfejs zawiera parametry do wyboru modelu, wiadomości, trybu strumieniowego i ustawień maksymalnych tokenów."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}
```

## Użycie narzędzi (Tool Use)

API wiadomości Claude natywnie wspiera funkcję wywoływania narzędzi, pozwalając modelowi na wywoływanie zdefiniowanych przez Ciebie narzędzi/funkcji w razie potrzeby.

### Przykład w Pythonie

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Pobierz aktualną pogodę w danej lokalizacji",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Miasto i stan, np. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Jaka jest pogoda w San Francisco?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Gdy model zdecyduje się na wywołanie narzędzia, odpowiedź będzie zawierać blok treści typu `tool_use`:

```json theme={null}
{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Pozwól, że sprawdzę pogodę w San Francisco dla Ciebie."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}
```

Zauważ, że `stop_reason` to `tool_use`, co oznacza, że model musi wywołać narzędzie. Po otrzymaniu tej odpowiedzi musisz wykonać funkcję narzędzia i zwrócić wynik w formie `tool_result` do modelu:

```python theme={null}
payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Pobierz aktualną pogodę w danej lokalizacji",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Miasto i stan, np. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Jaka jest pogoda w San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Pozwól, że sprawdzę pogodę w San Francisco dla Ciebie."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "San Francisco, CA"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Słonecznie, 72°F"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

Model wygeneruje ostateczną odpowiedź w naturalnym języku na podstawie wyników zwróconych przez narzędzie.

## Różnice między API zakończenia czatu a API wiadomości

XHuoAPI oferuje dwa formaty API Claude, a ich główne różnice są następujące:

| Cechy                | API wiadomości (`/v1/messages`)           | API zakończenia czatu (`/v1/chat/completions`)                   |
| -------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| Format               | Natywny format Anthropic                  | Format zgodny z OpenAI                                           |
| System prompt        | Niezależne pole `system`                  | Przekazywane przez `messages` w `role: "system"`                 |
| Struktura odpowiedzi | Tablica `content` (obsługuje wiele typów) | Tablica `choices` (zawiera `message`)                            |
| Format strumieniowy  | Wydarzenia SSE (wiele typów wydarzeń)     | Wiersze SSE `data`                                               |
| Głębokie myślenie    | Natywny parametr `thinking`               | Wywoływane przez specjalną nazwę modelu (np. sufiks `-thinking`) |
| Wywołanie narzędzi   | Natywne `tools` + `input_schema`          | Format `functions` zgodny z OpenAI                               |
| Statystyka tokenów   | `input_tokens` / `output_tokens`          | `prompt_tokens` / `completion_tokens`                            |

Jeśli Twój system już zintegrował API w formacie OpenAI, możesz użyć API zakończenia czatu do płynnego przełączenia. Jeśli potrzebujesz korzystać z pełnych natywnych możliwości Claude'a, zaleca się użycie API wiadomości.

## Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informacje. Na przykład:

* `400 token_mismatched`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
* `400 api_not_implemented`: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
* `401 invalid_token`: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacji.
* `429 too_many_requests`: Zbyt wiele żądań, przekroczono limit.
* `500 api_error`: Wewnętrzny błąd serwera, coś poszło nie tak na serwerze.

### Przykład odpowiedzi błędu

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "pobieranie nie powiodło się"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Wnioski

Dzięki temu dokumentowi zrozumiałeś, jak korzystać z API Claude Messages, aby wywołać funkcje konwersacyjne Claude w natywnym formacie Anthropic. API Messages obsługuje podstawowe rozmowy, systemowe podpowiedzi, odpowiedzi strumieniowe, wieloetapowe rozmowy, głębokie myślenie, zrozumienie wizualne i wywołania narzędzi. W razie jakichkolwiek pytań, prosimy o kontakt z naszym zespołem wsparcia technicznego.