Anthropic on Flask: use the sync client, keep the key in the server config

TL;DR

Install the SDK: pip install anthropic. Use the sync Anthropic() client in Flask views.

Steps

1. Install the SDK: pip install anthropic. Use the sync Anthropic() client in Flask views. Flask view functions run synchronously, so the sync client is the natural fit; the async client buys you nothing in a plain sync view.
2. Load the API key from your server config or environment into the client constructor. Keep it server-side. A Flask view is server code, which is exactly where the key belongs.
3. Build the request the same way as any Messages API call:

{
 "model": "claude-sonnet-5",
 "max_tokens": 1024,
 "system": "You answer concisely.",
 "messages": [{"role": "user", "content": "Explain idempotency keys."}]
}

2. system is a top-level parameter, not a message role. The Messages API reference defines it at the top level.
3. Extract the text from message.content (list of content blocks) and check message.stop_reason before returning JSON to the caller.
4. The SDK has built-in retries for transient failures (documented in the client-SDK overview), but a malformed request is your bug, not a retry candidate. Log the error type and message, fix the payload, and do not hammer the API.
5. Failure modes this prevents: awaiting a coroutine that never runs in a sync view; retrying malformed requests in a loop; reading the answer from the wrong field and returning an empty string.

When to use

You are seeing this: Load the API key from your server config or environment into the client constructor. Use this skill when you run into "Anthropic on Flask: use the sync client, keep the key in the server config".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The client-SDK docs list sync and async Python clients with built-in retries, and the Messages API reference defines system as a top-level parameter. Verified live at https://docs.anthropic.com/en/api/client-sdks and https://docs.anthropic.com/en/api/messages.