Hugging Face API quickstart for Python and cURL

Before you run anything

You need Python 3.10 or newer, a trusted local terminal, an authorized Hugging Face token with the permissions required by the selected inference route, and a model identifier that is actually available for your task. HFAPI.com does not create that account, supply credits, or validate access on your behalf. Provider requests may be billed.

Use an approved, non-sensitive prompt. Keep the experiment outside production systems and do not use a model output to authorize an external action. The official chat completion documentation describes the routed endpoint and its supported request structure; verify current model and provider support there.

Configure the local environment

The example reads HF_TOKEN and HF_MODEL from your environment. Never place the real token in a public website, source repository, or shell command that you intend to share. The following Bash example reads the token without echoing it to the terminal or embedding it in the command history:

read -rsp "Hugging Face token: " HF_TOKEN; printf '\n'
export HF_TOKEN
read -rp "Supported model identifier: " HF_MODEL
export HF_MODEL

An environment variable is a local configuration mechanism, not a universal secret-management solution. Keep the machine, terminal session, process environment, and diagnostic tools within an appropriate trust boundary. Use an approved secret manager for an actual application deployment.

Inspect the request

The compact examples below show the same basic chat request in Python and cURL. They are explanatory snippets, not browser-executable demos. The downloadable Python file adds bounds checking, sanitized errors, response-size limits, and completion-state validation.

The model is selected through your local configuration instead of a hard-coded availability claim. The request uses an explicit output limit. A returned string still requires task-specific quality checks before it should be trusted.

import json, os, urllib.request

url = "https://router.huggingface.co/v1/chat/completions"
body = {
    "model": os.environ["HF_MODEL"],
    "messages": [{"role": "user", "content": "Explain latency."}],
    "max_tokens": 128,
}
request = urllib.request.Request(
    url, data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["HF_TOKEN"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)
print(result["choices"][0]["message"]["content"])

# Trusted terminal only. Set HF_TOKEN and HF_MODEL first.
python3 -c 'import json, os; print(json.dumps({
  "model": os.environ["HF_MODEL"],
  "messages": [{"role": "user", "content": "Explain latency."}],
  "max_tokens": 128
}))' | curl --fail-with-body --max-time 30 \
  https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

# A response is generated text, not an approved action.
# See the downloadable Python example for validation.

Local example · Your model + token · Provider usage may be billed

Run the complete Python example

Download hfapi-quickstart.py, inspect its contents, then run it from the folder where you saved it:

python3 hfapi-quickstart.py --prompt "Explain latency versus throughput."

No third-party Python package is required. The file uses the standard library and sends a request directly to the configured Hugging Face routed chat endpoint using your credentials. Nothing is submitted through HFAPI.com.

The default output limit is 128 tokens. You can change it with --max-tokens within the file's documented bounds. The --timeout option configures a socket-operation timeout; it is not a guaranteed total end-to-end deadline. Use --help to see the accepted options. A successful example prints content to your terminal, so do not run it with information you would not want recorded in local terminal history or logs.

Interpret the outcome

Outcome	What to inspect next
Missing configuration	Set both environment variables in the terminal that runs the script.
Authentication or permission error	Check token scope and the route's access requirements without exposing the token.
Unsupported or unavailable model	Verify the exact identifier, provider route, task, and account access.
Rate limit	Inspect provider guidance and your traffic budget before deciding whether another attempt is appropriate.
Timeout or connection failure	Treat the result as uncertain. The upstream request may have been processed.
Incomplete generation	Review output limits and the reported completion state. Do not accept a truncated result as complete.
Valid text	Check the answer against the task's evidence and acceptance criteria.

The file performs no automatic retries. An uncertain failure should not cause a hidden loop of potentially billable calls. Its structural checks do not verify that generated statements are true or that extracted fields match the intended source.

Clean up and continue

When the local experiment is finished, remove the variables from that shell with unset HF_TOKEN HF_MODEL. This does not revoke the underlying token. Revoke and replace an exposed credential through the provider's supported controls.

Read the full quickstart article for the integration reasoning. Then review token security, measurement, and model selection before expanding the workload.

Download Python example View security checklist

Your first model call.Your own environment.