xtekky/gpt4free · error · MissingAuthError

Add a "api_key"

Error message

Add a "api_key"

What it means

Raised by HuggingFaceMedia.create_async_generator when no api_key argument was supplied. HuggingFaceMedia routes media (image/video) generation through the HuggingFace router API which requires a bearer token, so the provider fails immediately with MissingAuthError rather than making a doomed request.

Source

Thrown at g4f/Provider/needs_auth/hf/HuggingFaceMedia.py:141

        model: str,
        messages: Messages,
        api_key: str = None,
        extra_body: dict = None,
        prompt: str = None,
        proxy: str = None,
        timeout: int = 0,
        # Video & Image Generation
        n: int = 1,
        aspect_ratio: str = None,
        # Only for Image Generation
        height: int = None,
        width: int = None,
        # Video Generation
        resolution: str = "480p",
        **kwargs,
    ):
        if not api_key:
            raise MissingAuthError('Add a "api_key"')
        if extra_body is None:
            extra_body = {}
        selected_provider = None
        if model and ":" in model:
            model, selected_provider = model.split(":", 1)
        elif not model:
            model = cls.get_models()[0]
        prompt = format_media_prompt(messages, prompt)
        provider_mapping = await cls.get_mapping(model, api_key)
        headers = {
            "Accept-Encoding": "gzip, deflate",
            "Content-Type": "application/json",
            "Prefer": "wait",
        }
        new_mapping = {
            "hf-free" if key == "hf-inference" else key: value
            for key, value in provider_mapping.items()
            if key in ["replicate", "together", "hf-inference"]

View on GitHub (pinned to 973504e177)

Solutions

1. Create a HuggingFace access token at huggingface.co/settings/tokens
2. Pass it as api_key when calling the provider, or configure it in g4f provider settings
3. Verify the token has the required scope for inference/router calls
4. If you wanted keyless access, use the hf-free text providers instead of HuggingFaceMedia

Example fix

# before
response = await HuggingFaceMedia.create_async_generator(model='...', messages=messages)
# after
response = await HuggingFaceMedia.create_async_generator(model='...', messages=messages, api_key='hf_xxx')

if not api_key:
    api_key = os.environ.get('HF_API_KEY')
if not api_key:
    raise SystemExit('Set HF_API_KEY or pass api_key= for HuggingFaceMedia')

When it happens

Trigger: Calling a HuggingFaceMedia model (image or video generation) without passing api_key (via kwargs, provider settings, or env-based auth).

Common situations: Assuming hf-free-style access works for media models; forgetting to configure auth for a needs_auth provider; passing the key under the wrong kwarg name.

Related errors

• No Yupp accounts configured. Set YUPP_API_KEY environment va
• Cannot validate GLM account (status {response.status})
• API key has failed too many times.
• Add a "api_key"
• Model is not supported: {model} in: {cls.__name__}

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/93868ee97c9c01f6. Report an issue: GitHub.