Skip to main content
Anthropic Claude är ett mycket kraftfullt AI-konversationssystem som kan generera flytande och naturliga svar på bara några sekunder genom att mata in en prompt. Claude Messages API är Anthropics officiella inbyggda API-format, som skiljer sig från OpenAI:s kompatibla format (Chat Completion) genom att det använder Anthropics egna begäran och svarstruktur, vilket gör det möjligt att bättre utnyttja Claudes unika förmågor, såsom multimodal innehållsinmatning, verktygsanrop, djup tänkande (Extended Thinking) och andra avancerade funktioner. Detta dokument beskriver huvudsakligen användningsflödet för Claude Messages API, vilket gör att vi kan använda ett inbyggt gränssnitt som är i linje med Anthropics officiella för att anropa Claudes konversationsfunktioner.

Ansökningsprocess

För att använda Claude Messages API, börja med att gå till Ace Data Cloud-konsolen för att hämta din API-token, som du ska spara för framtida bruk. Om du inte har loggat in eller registrerat dig kommer du automatiskt att omdirigeras till inloggningssidan där du uppmanas att registrera dig och logga in. När detta är klart kommer du automatiskt att återvända till den aktuella sidan. En API-token räcker för att anropa alla plattformens tjänster, det behövs ingen separat ansökan för varje tjänst. Första ansökan ger en gratis kvot för att prova; om kvoten tar slut kan du ladda på allmän balans i konsolen.
📘 Fullständig dokumentation: Claude Messages API →

Grundläggande Användning

Begärningsvägen för Claude Messages API är /v1/messages, vilket är i linje med Anthropics officiella API. Vi behöver minst tillhandahålla tre obligatoriska parametrar:
  • model: Välj vilken Claude-modell som ska användas. Den senaste flaggskeppsmodellen är claude-fable-5-1 (1 miljon token kontext, max utdata 128K token); den ursprungliga claude-fable-5 är fortfarande kompatibel och kvar.
  • messages: Inmatningsmeddelandearray, där varje meddelande innehåller role (roll) och content (innehåll), där role stöder user och assistant.
  • max_tokens: Max antal utdata-token, som används för att begränsa längden på ett enstaka svar.
Vanliga valfria parametrar:
  • system: Systemprompt, som används för att ställa in modellens beteende och roll.
  • temperature: Genereringsslumptal, mellan 0-1, ju högre värde desto mer spridda svar.
  • stream: Om strömmande svar ska användas, sätt till true för att uppnå tecken-för-tecken återgivning.
  • stop_sequences: Anpassade stoppsekvenser, modellen slutar generera när den stöter på dessa texter.
  • top_p: Kärnprovningsparameter, som tillsammans med temperature kontrollerar den genererade slumpmässigheten.
  • top_k: Prover endast från de K mest sannolika alternativen.
  • tools: Verktygsdefinition, som gör att modellen kan anropa externa funktioner.
  • tool_choice: Kontrollerar hur modellen använder de tillhandahållna verktygen.
  • cache_control: Skapar automatiskt en cache-punkt vid den sista cachade innehållsblocken i begäran; kan också skrivas på specifika innehållsblock.

cURL Exempel

Python Exempel

Efter anropet returneras följande resultat:
Förklaring av returresultatets fält:
  • id: Den unika identifieraren för detta meddelande.
  • type: Alltid message.
  • role: Alltid assistant.
  • content: Svarsinnehållsarray, där varje element innehåller type (som text) och motsvarande innehåll.
  • model: Namnet på modellen som hanterar begäran.
  • stop_reason: Anledningen till att det stoppades. Stabilt värde inkluderar end_turn, max_tokens, stop_sequence, tool_use, pause_turn (kan återge nuvarande assistant-innehåll oförändrat för att fortsätta), refusal och model_context_window_exceeded.
  • stop_sequence: Om det stoppades på grund av anpassad stoppsekvens, visas den matchande stoppsekvensens text.
  • stop_details: När stop_reason är refusal, kan det innehålla avvisningskategori och förklaring.
  • usage: Token-användningsstatistik. input_tokens är icke-cachad inmatning; cache_creation_input_tokens och cache_read_input_tokens är respektive cache-skrivning och läsning; output_tokens är antalet utdata-token. Fable 5.1:s officiella cache-läsningsbaspris är 0.25/miljontoken,5minuteroch1timmescacheskrivningsbasprisa¨rrespektive0.25/miljon token, 5 minuter och 1 timmes cache-skrivningsbaspris är respektive 12.50 och $20/miljon token; plattformens faktiska priser beräknas enligt paketrabatter. Icke-strömmande svar kan också innehålla cost registrerat av Ace Data Cloud.

Systemprompt

Claude Messages API stöder att ställa in systemprompt genom system-fältet, vilket används för att definiera modellens beteende, roll och kontext.

Python Exempel

Genom att ställa in system-prompten kan man exakt kontrollera Claudes roll och beteende.

Strömmande Svar

Detta gränssnitt stöder också strömmande svar, sätt stream-parametern till true för att få en stegvis återgivningseffekt, vilket är mycket lämpligt för att implementera tecken-för-tecken visning på en webbsida.

Python Exempel

Strömmande svar returneras i Server-Sent Events (SSE) format, varje rad inleds med event: och data:. Strömmande händelsetyper inkluderar:
  • message_start: Meddelande börjar, innehåller grundläggande information om meddelandet och modellnamnet.
  • content_block_start: Innehållsblock börjar.
  • content_block_delta: Innehållsblockens inkrementella uppdatering, innehåller nygenererade textstycken.
  • content_block_stop: Innehållsblock slutar.
  • message_delta: Meddelande-nivåns inkrementella uppdatering, innehåller stop_reason och slutlig usage information.
  • message_stop: Meddelande slutar.
Utdata ser ut som följer:
Som man kan se, innehåller den strömmande responsen content_block_delta händelser som innehåller stegvis genererat textinnehåll, genom att sammanfoga alla text_delta kan man få den fullständiga svaret.

JavaScript Exempel

Flera rundor av dialog

Om du vill ansluta till flera rundor av dialogfunktioner, behöver du växla mellan user och assistant roller i messages arrayen och inkludera tidigare dialoghistorik.

Python Exempel

Returresultatet ser ut som följer:
Genom att skicka den fullständiga dialoghistoriken i messages, kan Claude kombinera kontexten för att ge exakta svar.

Djup tänkande modell

Claudes tänkande och tänkande sammanfattning är två olika koncept: modellen kan utföra intern resonemang, men API:et returnerar inte den ursprungliga tankekedjan. När resonemangsprocessen behöver visas, returnerar API:et en bearbetad sammanfattning. Den aktuella modellen rekommenderar att använda adaptivt tänkande och kontrollera den totala resonemangsinsatsen genom output_config.effort:
Tänkande blocket i svaret ser ut som:
  • display: "summarized" returnerar en läsbar sammanfattning av tankarna; det är inte den ursprungliga tankekedjan.
  • display: "omitted" returnerar thinking: "", men behåller fortfarande den oklara signature för att stödja efterföljande dialog.
  • Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 och Opus 4.7 har som standard omitted för display; Opus 4.6, Sonnet 4.6 och tidigare modeller som stöder tänkande använder som standard summarized.
  • Display påverkar endast det returnerade innehållet och strömmande fördröjning, stänger inte av resonemanget och minskar inte kostnaden för tänkande tokens.
  • Huruvida tänkande är som standard aktiverat och standardvärdet för display är två oberoende frågor. Opus 5, Sonnet 5 är som standard aktiverat för adaptivt tänkande; Opus 4.8, 4.7 och 4.6 måste aktiveras uttryckligen.
  • budget_tokens används endast för äldre modeller som fortfarande stöder fast tänkande budget. Nya modeller bör använda thinking.type=adaptive och output_config.effort; Fable 5.1:s tänkande är alltid aktiverat och kan inte stängas av uttryckligen.
  • Vid flera rundor av dialog och verktygsanrop bör den fullständiga tänkande blocket och signaturen som returneras av assistenten skickas tillbaka oförändrat; ändra inte eller generera signaturen själv.
  • Vissa kompatibla rutter kan inte hantera redacted_thinking eller stänga av tänkande utan förlust, i sådana fall returneras parameterfel och tyst inte tas bort eller ändrar begärans semantik.
I strömmande begäran kommer summarized att producera thinking_delta; omitted producerar inte thinking_delta, utan behåller endast livscykeln för tänkande block och signature_delta.

Visuell modell

Använda URL-bilder

cURL-exempel

Stödda bildformat inkluderar: image/jpeg, image/png, image/gif, image/webp.

Dokument och PDF

PDF använder document innehållsblock och stöder både Base64 och URL som stabila källor. Base64-källan måste använda application/pdf:
URL-källan skrivs som {"type":"url","url":"https://example.com/report.pdf"}. document stöder också text/plain och content källor som består av text/bild block; valfria fält inkluderar title, context och citations. Files API:s file_id källa tillhör en oberoende beta-funktion och ingår inte i detta gränssnitts stabila avtal.

Cache för förslag

Övergripande cache_control kommer automatiskt att placera cache-punkten på det sista cachade blocket:
När du behöver exakt kontroll över positionen kan du också skriva samma cache_control på text-, bild-, dokument-, tool_use-, tool_result innehållsblock eller verktygsdefinitioner. ttl stöder 5m (standard) och 1h; kontrollera cache-skrivning och träffar med usage.cache_creation_input_tokens och usage.cache_read_input_tokens. Exempel på returresultat:

Verktygsanrop (Tool Use)

Claude Messages API stöder inbyggt verktygsanrop, vilket tillåter modellen att anropa dina fördefinierade verktyg/funktioner vid behov.

Python-exempel

När modellen beslutar att anropa ett verktyg kommer returresultatet att innehålla content med en typ av tool_use innehållsblock:
Observera att stop_reason är tool_use, vilket indikerar att modellen behöver anropa ett verktyg. När du får detta resultat måste du utföra verktygsfunktionen och återföra resultatet i form av tool_result till modellen:
Modellen kommer att generera det slutliga naturliga språkssvaret baserat på resultatet från verktyget.

Skillnader mellan Chat Completion API

Ace Data Cloud erbjuder två format för Claude API, de huvudsakliga skillnaderna är som följer: Messages API:s usage.input_tokens representerar endast icke-cachad indata, cache_read_input_tokens och cache_creation_input_tokens är oberoende faktureringskategorier; de tre kommer att beräknas enligt motsvarande priser. Om ditt system redan är integrerat med OpenAI-formatet kan du använda Chat Completion API för en sömlös övergång. Om du behöver använda Claudes fulla inhemska kapacitet rekommenderas det att använda Messages API.

Felhantering

Felresponsen från den offentliga API:n använder Ace Data Cloud-plattformens envelope: error.code är en stabil felkod, error.message är en beskrivning, trace_id används för att spåra begäran. Vanliga HTTP-statusar inkluderar:
  • 400: Begärningsparametrar eller protokollinnehåll är ogiltiga.
  • 401: Auktoriseringstoken är ogiltig, saknas eller har gått ut.
  • 403: Åtkomst förbjuden, otillräcklig balans eller begränsad kvot.
  • 404: API eller modell finns inte.
  • 413: Begärningskropp för stor.
  • 429: För många begärningar.
  • 500 / 503 / 504: Tjänstfel, tillfälligt otillgänglig eller tidsgräns för behandling.

Exempel på felrespons

Denna felstruktur är Ace Data Clouds runtime-kontrakt och är inte likvärdig med Anthropic officiella fel envelope; vänligen hantera enligt HTTP-status och error.code.

Slutsats

Genom detta dokument har du fått en förståelse för hur man använder Claude Messages API för att anropa Claudes samtalsfunktioner i Anthropic inhemskt format. Messages API stöder grundläggande samtal, systemprompt, strömmande svar, flerrundiga samtal, djup tänkande, visuell förståelse, PDF, promptcache och verktygsanrop bland andra rika funktioner. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam.