Wniosek o Claude Messages API i jego użycie

Anthropic Claude to bardzo potężny system konwersacyjny AI, który po prostu po wprowadzeniu promptu potrafi w ciągu kilku sekund wygenerować płynną i naturalną odpowiedź. Claude Messages API to oficjalny, natywny format API Anthropic. W odróżnieniu od formatu kompatybilnego z OpenAI (Chat Completion), wykorzystuje własną strukturę żądań i odpowiedzi Anthropic, co pozwala lepiej wykorzystywać unikalne możliwości Claude, takie jak wielomodalne wprowadzanie treści, wywoływanie narzędzi, pogłębione myślenie (Extended Thinking) oraz inne zaawansowane funkcje. Ten dokument przedstawia głównie proces korzystania z Claude Messages API. Za jego pomocą możemy używać natywnego interfejsu zgodnego z oficjalnym Anthropic do wywoływania funkcji konwersacyjnych Claude.

Proces składania wniosku

Aby korzystać z Claude Messages API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go do późniejszego użycia.

Jeśli nie jesteś jeszcze zalogowany ani zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, gdzie zostaniesz zaproszony do rejestracji i zalogowania się. Po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności składania osobnego wniosku dla każdej usługi. Przy pierwszym wniosku otrzymasz bezpłatny limit, aby móc korzystać z bezpłatnego okresu próbnego; gdy limit będzie niewystarczający, możesz doładować uniwersalne saldo w konsoli.

📘 Pełna dokumentacja: Claude Messages API →

Podstawowe użycie

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

model: wybór używanego modelu Claude. claude-opus-5-5 jest dostępny wyłącznie przez Messages API, obsługuje kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów i zawsze ma włączone adaptacyjne myślenie. Najnowszym flagowym modelem jest claude-fable-5-1 (kontekst 1 miliona Tokenów, maksymalne wyjście 128K Tokenów); wcześniejszy claude-fable-5 pozostaje nadal zachowany dla zgodności. claude-sonnet-5-5 został dodany do natywnego interfejsu serii Messages i obsługuje wejście obrazowe oraz adaptacyjne myślenie; jego oficjalne ceny referencyjne za wejście, wyjście i odczyt z pamięci podręcznej wynoszą odpowiednio 2, 10 i 0,20 USD za milion Tokenów.
messages: tablica wprowadzanych wiadomości, gdzie każda wiadomość zawiera role (rolę) oraz content (treść), a role obsługuje user i assistant.
max_tokens: maksymalna liczba tokenów wyjściowych, używana do ograniczania długości pojedynczej odpowiedzi.

Często używane parametry opcjonalne:

system: systemowy prompt, używany do ustawiania zachowania i roli modelu.
temperature: losowość generowania, wartość od 0 do 1; im większa wartość, tym bardziej rozbieżne odpowiedzi.
stream: czy używać odpowiedzi strumieniowej; ustawienie na true pozwala uzyskać efekt zwracania znak po znaku.
stop_sequences: niestandardowe sekwencje zatrzymania; model przestanie generować po napotkaniu tych tekstów.
top_p: parametr próbkowania jądrowego, który wraz z temperature kontroluje losowość generowania.
top_k: próbkuje wyłącznie spośród K opcji o najwyższym prawdopodobieństwie.
tools: definicje narzędzi, używane, aby umożliwić modelowi wywoływanie funkcji zewnętrznych.
tool_choice: kontroluje sposób używania przez model dostarczonych narzędzi.
cache_control: automatycznie tworzy punkt przerwania pamięci podręcznej przy ostatnim buforowalnym bloku treści w żądaniu; można go również umieścić w konkretnym bloku treści.

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-fable-5-1",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

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-fable-5-1",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

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

Po wywołaniu wynik zwracany jest 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-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Opis pól wyniku zwracanego:

id: unikalny identyfikator tej wiadomości.
type: zawsze message.
role: zawsze assistant.
content: tablica treści odpowiedzi, gdzie każdy element zawiera type (np. text) oraz odpowiadającą mu treść.
model: nazwa modelu przetwarzającego żądanie.
stop_reason: powód zatrzymania. Stabilne wartości obejmują end_turn, max_tokens, stop_sequence, tool_use, pause_turn (można zwrócić bieżącą treść assistant bez zmian, aby kontynuować), refusal oraz model_context_window_exceeded.
stop_sequence: jeśli zatrzymanie nastąpiło z powodu niestandardowej sekwencji zatrzymania, wyświetla pasujący tekst sekwencji zatrzymania.
stop_details: gdy stop_reason ma wartość refusal, może zawierać kategorię odmowy oraz opis.
usage: statystyki użycia tokenów. input_tokens oznacza niewykorzystane z pamięci podręcznej wejście; cache_creation_input_tokens i cache_read_input_tokens oznaczają odpowiednio zapis i odczyt z pamięci podręcznej; output_tokens to całkowita liczba tokenów wyjściowych. Jeśli zwracane jest output_tokens_details.thinking_tokens, wartość ta jest podzbiorem output_tokens i nie należy jej ponownie dodawać przy obliczaniu sumy lub kosztu. Gdy brak autorytatywnego licznika dla tego zestawienia, może ono mieć wartość null lub zostać pominięte.
usage.cache_creation: opcjonalne zestawienie TTL zapisu do pamięci podręcznej, zawierające ephemeral_5m_input_tokens oraz ephemeral_1h_input_tokens. Gdy obiekt istnieje, suma obu wartości jest równa cache_creation_input_tokens; wartość pola null lub pominięcie oznacza, że bieżąca odpowiedź nie ma dostępnego podziału TTL i nie może być interpretowana jako 0.
usage.cost: odpowiedzi niestrumieniowe mogą zawierać obiekt zużycia limitu zarejestrowany przez Ace Data Cloud, gdzie amount oznacza rzeczywiste zużycie w tym przypadku, currency jest jednostką rozliczeniową, a list_amount to kwota przed rabatem (jeśli występuje). Oficjalne ceny bazowe Fable 5.1 za odczyt z pamięci podręcznej wynoszą $0.25/milion Tokenów, a ceny bazowe zapisu do pamięci podręcznej na 5 minut i 1 godzinę wynoszą odpowiednio $12.50 i $20/milion Tokenów; rzeczywiste ceny na platformie są przeliczane zgodnie z rabatem pakietu.

Systemowy prompt

Claude Messages API obsługuje ustawianie systemowego promptu za pomocą pola system, używanego do definiowania zachowania, roli i kontekstu modelu.

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,
    "system": "你是一位专业的中文翻译助手，请将用户输入的英文翻译成中文。",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

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

Poprzez ustawienie promptu system można precyzyjnie kontrolować rolę i sposób działania Claude.

Odpowiedzi strumieniowe

Ten interfejs również obsługuje odpowiedzi strumieniowe — ustawienie parametru stream na true umożliwia uzyskanie efektu stopniowego zwracania, co bardzo dobrze nadaje się do implementacji wyświetlania znak po znaku na stronie internetowej.

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,
    "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"))

Odpowiedź strumieniowa jest zwracana w formacie Server-Sent Events (SSE), a każda linia rozpoczyna się od event: i data:. Typy zdarzeń strumieniowych obejmują:

message_start: rozpoczęcie wiadomości, zawiera podstawowe informacje o wiadomości i nazwę modelu.
content_block_start: rozpoczęcie bloku treści.
content_block_delta: przyrostowa aktualizacja bloku treści, zawiera nowo wygenerowany fragment tekstu.
content_block_stop: zakończenie bloku treści.
message_delta: przyrostowa aktualizacja na poziomie wiadomości, zawiera informacje stop_reason i końcowe usage. Miarodajną wartość output_tokens_details.thinking_tokens należy odczytywać wyłącznie z ostatniego message_delta.usage, nie należy sumować jej między zdarzeniami.
message_stop: zakończenie wiadomości.

Wynik 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":"Hi"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! My name is"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Claude. How can I help you today?"}}

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

Jak widać, w odpowiedzi strumieniowej zdarzenia content_block_delta zawierają stopniowo generowaną treść tekstową, a pełną odpowiedź można uzyskać przez połączenie wszystkich text_delta.

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: "Hello, 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));
}

Rozmowy wieloturowe

Jeśli chcesz podłączyć funkcję rozmów wieloturowych, musisz naprzemiennie umieścić wiadomości o rolach user i assistant w tablicy messages, przekazując jednocześnie poprzednią 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": "Hello, my name is Alice."},
        {"role": "assistant", "content": "Hello Alice! Nice to meet you. How can I help you today?"},
        {"role": "user", "content": "What is my name?"}
    ]
}

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

Wynik zwracany jest następujący:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Your name is Alice, as you just told me!"
    }
  ],
  "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 udzielać dokładnych odpowiedzi z uwzględnieniem kontekstu.

Model głębokiego rozumowania

Thinking i thinking summary Claude to dwa różne pojęcia: model może przeprowadzać wewnętrzne rozumowanie, ale API nie zwraca oryginalnego łańcucha myśli. Gdy wymagane jest wyświetlenie procesu rozumowania, API zwraca przetworzone podsumowanie. Obecne modele zalecają używanie adaptive thinking oraz kontrolowanie ogólnego nakładu rozumowania za pomocą output_config.effort:

import requests

url = "https://api.acedata.cloud/v1/messages"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
payload = {
    "model": "claude-opus-5",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive",
        "display": "summarized"
    },
    "output_config": {
        "effort": "high"
    },
    "messages": [
        {"role": "user", "content": "What is the sine of 30 degrees?"}
    ]
}

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

Blok thinking w odpowiedzi wygląda następująco:

{
  "type": "thinking",
  "thinking": "The problem asks for a standard trigonometric value...",
  "signature": "opaque-signature"
}

display: "summarized" zwraca czytelne podsumowanie toku rozumowania; nie jest ono surowym łańcuchem myśli.
display: "omitted" zwraca thinking: "", ale nadal zachowuje nieprzezroczysty signature, aby wspierać kolejne rozmowy.
display: "updates" to tryb beta Anthropic, który wymaga przekazania anthropic-beta: thinking-display-updates-2026-08-18. Oficjalna definicja mówi o ukryciu treści rozumowania i wyświetlaniu krótkich aktualizacji postępu między wywołaniami narzędzi. Platforma przekazuje ten parametr i nagłówek żądania beta w oryginalnej wartości, nie wymusza jego przepisania na summarized; rzeczywista zawartość wyjścia zależy od wsparcia wybranego modelu.
thinking, output_config, effort, parametry próbkowania oraz nowe rozszerzone pola są przekazywane w oryginalnych wartościach. Platforma nie utrzymuje zakodowanych na stałe według modeli wyliczeń wartości ani ograniczeń kombinacji, ani nie przepisuje automatycznie trybu thinking; o akceptacji tych parametrów decyduje wybrany model, a błędy parametrów zwrócone przez model są przekazywane klientowi.
Domyślną wartością display dla Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 i Opus 4.7 jest omitted; Opus 4.6, Sonnet 4.6 oraz wcześniejsze modele obsługujące thinking domyślnie używają summarized.
Display wpływa tylko na zwracaną zawartość i opóźnienie strumieniowania, nie wyłącza rozumowania ani nie zmniejsza rozliczania tokenów thinking.
To, czy thinking jest domyślnie włączone, oraz domyślna wartość display to dwa niezależne zagadnienia. Opus 5 i Sonnet 5 domyślnie włączają adaptive thinking; dla Opus 5 pominięcie thinking jest równoważne adaptive, a pominięcie output_config.effort jest równoważne high. Opus 4.8, 4.7 i 4.6 wymagają jawnego włączenia.
Thinking i końcowa treść wspólnie wykorzystują budżet wyjściowy max_tokens. Gdy budżet jest zbyt mały, thinking może wykorzystać większość limitu, przez co treść może być pusta lub obcięta; zwiększ max_tokens albo użyj effort low / medium, aby kontrolować nakład rozumowania.
Dla modeli pozwalających wyłączyć thinking można przekazać thinking: {"type":"disabled"}. Nowe tryby, takie jak between_tools, oraz kombinacje effort zależą od wybranego modelu; platforma nie odrzuca ich z wyprzedzeniem na podstawie starych reguł dotyczących modeli.
Stały budżet rozumowania można przekazać przez budget_tokens; nowe modele zazwyczaj używają thinking.type=adaptive i output_config.effort. To, czy obsługiwany jest stały budżet lub wyłączenie myślenia, zależy od aktualnych możliwości wybranego modelu.
W rozmowach wieloturowych i przy wywołaniach narzędzi należy zwracać w niezmienionej postaci pełny blok thinking oraz signature zwrócone przez assistant; nie modyfikuj ani nie generuj samodzielnie signature.
Przekazywanie parametrów nie oznacza, że każdy model obsługuje wszystkie funkcje. Wywołania między protokołami nadal wymagają konwersji, a zakres wsparcia i błędy dla treści takich jak redacted_thinking są określane przez usługę modelu faktycznie przetwarzającą żądanie.

W żądaniach strumieniowych summarized generuje thinking_delta; omitted nie generuje thinking_delta, zachowuje jedynie cykl życia bloku thinking i signature_delta.

Modele wizyjne

Claude obsługuje wejścia multimodalne i może jednocześnie przetwarzać tekst oraz obrazy. W Messages API możliwości wizyjne można wykorzystać, ustawiając content w formacie tablicy i przekazując blok zawartości obrazu.

Używanie obrazów zakodowanych w Base64

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

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

# 读取并编码图片
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": "What's in this image?"
                }
            ]
        }
    ]
}

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

Używanie obrazów 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": "What's in this image?"
                }
            ]
        }
    ]
}

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

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": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "What'\''s in this image?"
          }
        ]
      }
    ]
  }'

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

Dokumenty i PDF

PDF używa bloku zawartości document, obsługując dwa stabilne źródła: Base64 i URL. Źródło Base64 musi używać application/pdf:

import base64

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "messages": [{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data
                },
                "title": "Quarterly report"
            },
            {"type": "text", "text": "Summarize this PDF."}
        ]
    }]
}

Źródło URL zapisuje się jako {"type":"url","url":"https://example.com/report.pdf"}. document obsługuje również text/plain oraz źródło content złożone z bloków text/image; opcjonalne pola obejmują title, context i citations. Źródło file_id w Files API należy do niezależnej funkcji beta i nie jest objęte stabilnym kontraktem tego interfejsu.

Buforowanie promptów

Najwyższy poziom cache_control automatycznie umieszcza punkt przerwania pamięci podręcznej na ostatnim bloku możliwym do buforowania:

payload = {
    "model": "claude-fable-5-1",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral", "ttl": "5m"},
    "system": "You are an expert on this reference material.",
    "messages": [{"role": "user", "content": "Summarize the key points."}]
}

Gdy wymagane jest precyzyjne sterowanie pozycją, można również zapisać tę samą wartość cache_control w blokach zawartości text, image, document, tool_use, tool_result lub w definicji narzędzia. ttl obsługuje 5m (domyślnie) i 1h; proszę użyć usage.cache_creation_input_tokens oraz usage.cache_read_input_tokens, aby określić zapis do pamięci podręcznej i trafienia w pamięci podręcznej. Gdy odpowiedź zawiera usage.cache_creation, ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens. Jeżeli cache_creation ma wartość null lub jest pominięte, oznacza to, że istnieje jedynie łączna wartość zapisów do pamięci podręcznej, bez autorytatywnego podziału TTL; w takim przypadku nie należy traktować żadnego bucketu jako znanego 0, a rozliczenia i sumy nadal opierają się na polu zagregowanym. Przykład zwracanego wyniku:

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an API request configuration interface for what appears to be an AI chat completion service. The interface includes parameters for model selection, messages, stream mode, and max tokens settings."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Wywoływanie narzędzi (Tool Use)

Claude Messages API natywnie obsługuje funkcję wywoływania narzędzi, umożliwiając modelowi wywoływanie zdefiniowanych przez Państwa narzędzi/funkcji, gdy jest to potrzebne.

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,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
}

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

Gdy model zdecyduje się wywołać narzędzie, content w zwracanym wyniku będzie zawierać blok zawartości typu tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me check the weather in San Francisco for you."
    },
    {
      "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
  }
}

Należy zwrócić uwagę, że stop_reason ma wartość tool_use, co oznacza, że model musi wywołać narzędzie. Po otrzymaniu tego wyniku należy wykonać funkcję narzędzia i przekazać wynik z powrotem do modelu w formie tool_result:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "What's the weather like in San Francisco?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Let me check the weather in San Francisco for you."},
                {"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": "Sunny, 72°F"
                }
            ]
        }
    ]
}

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

Model wygeneruje końcową odpowiedź w języku naturalnym na podstawie wyniku zwróconego przez narzędzie.

Różnice względem Chat Completion API

Ace Data Cloud udostępnia jednocześnie dwa formaty Claude API, a ich główne różnice są następujące: usage.input_tokens w Messages API oznacza wyłącznie dane wejściowe niepochodzące z pamięci podręcznej, a cache_read_input_tokens i cache_creation_input_tokens są niezależnymi bucketami rozliczeniowymi; wszystkie trzy są obliczane osobno według odpowiadających im cen.

Funkcja	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
Format	Natywny format Anthropic	Format zgodny z OpenAI
Komunikat systemowy	Niezależne pole `system`	Przekazywany przez `role: "system"` w `messages`
Struktura odpowiedzi	Tablica `content` (obsługuje wiele typów)	Tablica `choices` (zawiera `message`)
Format strumieniowy	Zdarzenia SSE (wiele typów zdarzeń)	Wiersze SSE `data`
Głębokie rozumowanie	Natywne `thinking` i `output_config.effort`	Domyślna strategia modelu i parametry zgodności
Wywoływanie narzędzi	Natywne `tools` + `input_schema`	Format `tools` zgodny z OpenAI
Statystyki tokenów	`output_tokens_details.thinking_tokens`	`completion_tokens_details.reasoning_tokens`

Jeśli Państwa system jest już zintegrowany z API w formacie OpenAI, można użyć Chat Completion API, aby bezproblemowo się przełączyć. Jeśli potrzebują Państwo wszystkich natywnych możliwości Claude, zaleca się użycie Messages API.

Obsługa błędów

Odpowiedzi błędów publicznego interfejsu używają envelope platformy Ace Data Cloud: error.code jest stabilnym kodem błędu, error.message jest opisem, a trace_id służy do diagnozowania żądań. Typowe statusy HTTP obejmują:

400: Parametry żądania lub zawartość protokołu są nieprawidłowe.
401: Token autoryzacyjny jest nieprawidłowy, nieobecny lub wygasł.
403: Dostęp zabroniony, niewystarczające saldo lub ograniczony limit.
404: API lub model nie istnieje.
413: Treść żądania jest zbyt duża.
429: Zbyt wiele żądań.
500 / 503 / 504: Błąd usługi, tymczasowa niedostępność lub przekroczenie limitu czasu przetwarzania.

Przykład odpowiedzi błędu

{
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Ta struktura błędu jest kontraktem wykonawczym Ace Data Cloud i nie jest równoważna oficjalnemu envelope błędu Anthropic; należy obsługiwać ją zgodnie ze statusem HTTP i error.code.

Wnioski

Dzięki temu dokumentowi wiesz już, jak używać Claude Messages API do wywoływania funkcji konwersacyjnych Claude w natywnym formacie Anthropic. Messages API obsługuje bogate funkcje, takie jak podstawowe rozmowy, prompty systemowe, odpowiedzi strumieniowe, rozmowy wieloturowe, głębokie myślenie, rozumienie obrazu, PDF-y, buforowanie promptów i wywoływanie narzędzi. Jeśli masz jakiekolwiek pytania, skontaktuj się z naszym zespołem wsparcia technicznego w dowolnym momencie.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Wniosek o Claude Messages API i jego użycie

Proces składania wniosku

Podstawowe użycie

Przykład cURL

Przykład Python

Systemowy prompt

Przykład Python

Odpowiedzi strumieniowe

Przykład Python

Przykład JavaScript

Rozmowy wieloturowe

Przykład Python

Model głębokiego rozumowania

Modele wizyjne

Używanie obrazów zakodowanych w Base64

Używanie obrazów URL

Przykład cURL

Dokumenty i PDF

Buforowanie promptów

Wywoływanie narzędzi (Tool Use)

Przykład Python

Różnice względem Chat Completion API

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski

​Proces składania wniosku

​Podstawowe użycie

​Przykład cURL

​Przykład Python

​Systemowy prompt

​Przykład Python

​Odpowiedzi strumieniowe

​Przykład Python

​Przykład JavaScript

​Rozmowy wieloturowe

​Przykład Python

​Model głębokiego rozumowania

​Modele wizyjne

​Używanie obrazów zakodowanych w Base64

​Używanie obrazów URL

​Przykład cURL

​Dokumenty i PDF

​Buforowanie promptów

​Wywoływanie narzędzi (Tool Use)

​Przykład Python

​Różnice względem Chat Completion API

​Obsługa błędów

​Przykład odpowiedzi błędu

​Wnioski

Proces składania wniosku

Podstawowe użycie

Przykład cURL

Przykład Python

Systemowy prompt

Przykład Python

Odpowiedzi strumieniowe

Przykład Python

Przykład JavaScript

Rozmowy wieloturowe

Przykład Python

Model głębokiego rozumowania

Modele wizyjne

Używanie obrazów zakodowanych w Base64

Używanie obrazów URL

Przykład cURL

Dokumenty i PDF

Buforowanie promptów

Wywoływanie narzędzi (Tool Use)

Przykład Python

Różnice względem Chat Completion API

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski