> ## Documentation Index
> Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Hugging Face clients
> Call RunInfra Model APIs from huggingface_hub and @huggingface/inference by passing a base URL, with the verified model id mapping and capability matrix.
Both Hugging Face inference clients, `huggingface_hub` for Python and `@huggingface/inference` for JavaScript, accept an OpenAI-compatible base URL, so both call RunInfra today.
**RunInfra is not a registered Hugging Face Inference Provider.** Passing `provider="runinfra"` fails in both clients with a "provider not supported" error. Use the base-URL forms below. If that changes, this page is where the routed forms will appear.
## Python
```bash theme={"dark"}
pip install "huggingface_hub>=1.0"
export RUNINFRA_GATEWAY_KEY="rp_your_key_here"
```
```python theme={"dark"}
import os
from huggingface_hub import InferenceClient
client = InferenceClient(
base_url="https://api.runinfra.ai/v1",
api_key=os.environ["RUNINFRA_GATEWAY_KEY"],
)
completion = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "Write a TypeScript retry helper."}],
max_tokens=16384,
)
print(completion.choices[0].message.content)
```
Streaming is the same call with `stream=True`, reading `chunk.choices[0].delta.content`.
Verified on 2026-08-16 with `huggingface_hub` 1.27.0 against `https://api.runinfra.ai/v1`, non-streaming and streaming.
## JavaScript
Pass `endpointUrl` in the client options and your RunInfra key as the token. The client appends `/v1/chat/completions` for you, so give it the host with or without `/v1`.
```bash theme={"dark"}
npm install @huggingface/inference
export RUNINFRA_GATEWAY_KEY="rp_your_key_here"
```
```javascript theme={"dark"}
import { InferenceClient } from "@huggingface/inference";
const client = new InferenceClient(process.env.RUNINFRA_GATEWAY_KEY, {
endpointUrl: "https://api.runinfra.ai",
});
const completion = await client.chatCompletion({
model: "deepseek-v4-flash",
messages: [{ role: "user", content: "Write a TypeScript retry helper." }],
max_tokens: 16384,
});
console.log(completion.choices[0].message.content);
```
`chatCompletionStream` takes the same arguments and yields deltas.
Do not combine `endpointUrl` with an explicit third-party `provider`. The client rejects that combination with `Cannot use endpointUrl with a third-party provider`. Pass `endpointUrl` alone.
Verified on 2026-08-16 with `@huggingface/inference` 4.13.26, non-streaming and streaming.
## Model ids
These clients normally take a Hugging Face repository id. In the base-URL forms above you pass the RunInfra model id, because you are talking to RunInfra directly.
| RunInfra model id | Hugging Face repository |
| ---------------------------- | --------------------------------------------------- |
| `deepseek-v4-flash` | `deepseek-ai/DeepSeek-V4-Flash-0731` |
| `nemotron-3-5-lightning-30b` | `nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16` |
| `qwen3-8-27b` | `Qwen/Qwen3.8-27B` |
| `qwen3-8-2-4t-a95b` | `Inferact/Qwen3.8-2.4T-A95B-NVFP4` |
The gateway also accepts the repository id in the `model` field, so either string resolves. `GET /v1/models` returns the RunInfra ids and is the authoritative live list.
## What each model does
Working snippets for the conditional JSON case are in [Structured output](/docs/cookbook/structured-output). `reasoning_effort` is a plain top-level request field sent beside `response_format` in the same call; if your installed client's type definitions predate the `"none"` value, widen the literal at the call site, because the request that goes out is unchanged.
## Two behaviours worth knowing
**Reasoning arrives on a `reasoning` field.** These models think before they answer. That text streams on `delta.reasoning` and appears on `message.reasoning`, never on `content`. With a small `max_tokens` a model can spend the whole budget reasoning and return `content: null` with `finish_reason: "length"`. In one measurement, `nemotron-3-5-lightning-30b` returned no answer at `max_tokens: 96` and the complete answer at `max_tokens: 1200`.
**`deepseek-v4-flash` runs at maximum reasoning effort by default.** With no `reasoning_effort` sent, RunInfra sends the maximum for that model, so the id answers the same workload the public benchmarks of that name measure. On that same model, `high` and `xhigh` are also sent as maximum, because the serving stack accepts the intermediate values and then does not apply them. Both behaviours are specific to that one model, and it is the difference to control for if you are comparing hosts.
## Which client should you use
If you already live inside the Hugging Face ecosystem, the clients on this page work and nothing here changes later. Otherwise use the OpenAI client, which is the shortest path and what the rest of these docs assume. See [OpenAI compatibility](/docs/tools-sdks/openai-compatibility).
Either way, calls are billed by RunInfra against your workspace balance at the per-token price on each model's page. See [Pricing and credits](/docs/introduction/plans) and [Rate limits](/docs/api-reference/rate-limits).
## Related
The shortest path, and what the rest of these docs assume.
The full request contract.
How these calls are billed.