Claude Messages API 申请及使用

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 i kliknąć przycisk „Acquire”, aby uzyskać potrzebne poświadczenia do żądania:

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

curl -X POST 'https://api.acedata.cloud/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

import requests

url = "https://api.acedata.cloud/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:

{
  "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

import requests

url = "https://api.acedata.cloud/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

import requests

url = "https://api.acedata.cloud/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

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.acedata.cloud/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

import requests

url = "https://api.acedata.cloud/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:

{
  "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

import requests

url = "https://api.acedata.cloud/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:

{
  "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

import base64
import requests

url = "https://api.acedata.cloud/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

import requests

url = "https://api.acedata.cloud/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.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Co jest na tym obrazku?"
                }
            ]
        }
    ]
}

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

cURL przykład

curl -X POST 'https://api.acedata.cloud/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.acedata.cloud/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:

{
  "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

import requests

url = "https://api.acedata.cloud/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:

{
  "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:

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

Ace Data Cloud 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

{
  "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.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Proxy

Advanced

Claude Messages API 申请及使用

Proces aplikacji

Podstawowe użycie

Przykład cURL

Przykład w Pythonie

Systemowe podpowiedzi

Przykład w Pythonie

Odpowiedzi strumieniowe

Przykład w Pythonie

Przykład JavaScript

Wiele rund rozmowy

Przykład Python

Model głębokiego myślenia

Przykład Python

Model wizualny

Użycie obrazu zakodowanego w Base64

Użycie obrazu z URL

cURL przykład

Użycie narzędzi (Tool Use)

Przykład w Pythonie

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

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski

​Proces aplikacji

​Podstawowe użycie

​Przykład cURL

​Przykład w Pythonie

​Systemowe podpowiedzi

​Przykład w Pythonie

​Odpowiedzi strumieniowe

​Przykład w Pythonie

​Przykład JavaScript

​Wiele rund rozmowy

​Przykład Python

​Model głębokiego myślenia

​Przykład Python

​Model wizualny

​Użycie obrazu zakodowanego w Base64

​Użycie obrazu z URL

​cURL przykład

​Użycie narzędzi (Tool Use)

​Przykład w Pythonie

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

​Obsługa błędów

​Przykład odpowiedzi błędu

​Wnioski

Proces aplikacji

Podstawowe użycie

Przykład cURL

Przykład w Pythonie

Systemowe podpowiedzi

Przykład w Pythonie

Odpowiedzi strumieniowe

Przykład w Pythonie

Przykład JavaScript

Wiele rund rozmowy

Przykład Python

Model głębokiego myślenia

Przykład Python

Model wizualny

Użycie obrazu zakodowanego w Base64

Użycie obrazu z URL

cURL przykład

Użycie narzędzi (Tool Use)

Przykład w Pythonie

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

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski