Quick Start

FreeGPTHub provides a unified Python interface to call multiple LLM / MLLM endpoints via provider-specific *Endpoints clients. You create a ChatRequest, pick an endpoint client, and call send().

Notes: For security reasons, all free API keys collected by this project have been encrypted. Therefore, if you’d like to use this project, please first follow the WeChat Official Account “Charles的皮卡丘”, then send the message “FreeGPTHub” via private chat in the backend to obtain the key.

Supported Endpoint Clients (What you can import)

The repository currently lists these endpoint clients:

  • AlibabaQwenEndpoints

  • BaiduQianfanEndpoints

  • DeepSeekEndpoints

  • DoubaoEndpoints

  • IFLYTEKSparkEndpoints

  • MiniMaxEndpoints

  • ModelScopeEndpoints

  • OpenAIGPTEndpoints

  • ZhipuGLMEndpoints

You can switch providers by swapping the client class, while keeping the same ChatRequest.

Your First Call (iFLYTEK Spark)

This is the simplest “works-first” example from the repository.

from freegpthub import ChatRequest, IFLYTEKSparkEndpoints

# 1) prepare your request
req = ChatRequest(text="10 * 10 = ?")
# 2) create a client
spark_client = IFLYTEKSparkEndpoints(aes_gem_key=xxx)
# 3) call an endpoint version (provider-specific)
resp = spark_client.send(req=req, version="lite")
print(resp.text)
# 4) try another version
resp = spark_client.send(req=req, version="4.0Ultra")
print(resp.text)

If you get errors about aes_gem_key, please first follow the WeChat Official Account “Charles的皮卡丘”, then send the message “FreeGPTHub” via private chat in the backend to obtain the aes_gem_key.

Some paid models use the free credits from the accounts we created on the corresponding platforms. If you see an error, it means those free credits have been exhausted. You can switch to your own API key to continue using it.

Switch Providers (Same Pattern)

Example: ModelScope DeepSeek. The calling pattern is the same: create ChatRequest, create client, call send().

from freegpthub import ChatRequest, ModelScopeEndpoints

req = ChatRequest(text="Explain gradient descent in 3 sentences.")
client = ModelScopeEndpoints()
resp = client.send(req=req, version="deepseek-ai/DeepSeek-R1-0528")
print(resp.text)

Arguments & Data Structures (What they mean)

This section explains the core objects used by FreeGPTHub, based on the actual implementation.

ChatRequest

ChatRequest is the unified input object you pass into endpoint.send(...).

Fields:

  • text (str): The user prompt (default "").

  • images (Tuple[Any, ...]): Optional image inputs for vision-capable endpoints (default ()).

  • openai (Dict[str, Any]): Configuration for OpenAI SDK–style endpoints. You may pass model or messages here; if not provided, the library uses version as the model name and uses a default messages=[{"role":"user","content": req.text}].

  • websocket (Dict[str, Any]): Reserved for websocket-style endpoints (default {"client": {}}).

  • extra_payload (Dict[str, Any]): Provider-specific extra payload (default {}).

  • meta (Dict[str, Any]): Any metadata you want to carry for logging/debugging (default {}).

Minimal text-only request:

from freegpthub import ChatRequest

req = ChatRequest(text="10 * 10 = ?")

Vision request example (bytes / url / (bytes,mime) are all accepted):

from freegpthub import ChatRequest

req = ChatRequest(
    text="Describe this image.",
    images=(
        "https://example.com/demo.png",
        # open("demo.png", "rb").read(),
        # (open("demo.jpg", "rb").read(), "image/jpeg"),
    ),
)

ChatResponse

ChatResponse is the unified output returned by endpoint.send(...).

Fields:

  • text (str): The final generated text.

  • raw (Any): The original provider response object (useful for debugging).

  • api_used (str): Which API route was selected/used inside the endpoint (may be empty if not set).

  • variant_used (str): The fully-qualified variant id used (format: provider:model:version).

Example:

resp = endpoint.send(req=req, version="lite")
print(resp.text)
print(resp.api_used, resp.variant_used)

ModelIOType and Modality

FreeGPTHub routes requests by I/O modality using ModelIOType.

  • Modality is an enum with: TEXT, IMAGE, AUDIO, VIDEO.

  • ModelIOType defines:

    • inputs: a set of input modalities.

    • outputs: a set of output modalities.

Common tags:

  • T2T: text → text

  • TI2T: text+image → text (vision)

Utilities you may see:

  • ModelIOType.create(inputs=[...], outputs=[...]) to build an IO type.

  • ModelIOType.fromtag("T2T") to parse a tag.

  • detailedtag() returns explicit tags like TI2T.

  • tag may return canonical tags like MM2T when multiple inputs exist.

In the current BaseEndpoint.inferio(...), only ChatRequest is supported:

  • if req.images is empty: inferred IO is T2T.

  • if req.images is non-empty: inferred IO is TI2T.

BaseEndpoint.send(req, api=None, version=None, request_overrides=None)

send() is the core entry point for all endpoint clients.

Arguments:

  • req (Any): In practice, a ChatRequest. The library infers its IO type via inferio(req).

  • version (Optional[str]): Which variant to use. If omitted, it falls back to self.default_version. Must be registered in self.variants, otherwise ValueError.

  • api (Optional[str]): Force a specific API route (by name) within the chosen variant. If not provided, the endpoint automatically selects the highest-priority compatible API.

  • request_overrides (dict): Extra request options passed into the handler (implementation-specific).

EndpointRegistry (Discoverability)

EndpointRegistry collects all endpoints and can:

  • listall(): return describe() for every registered endpoint

  • findvariantsbyio(io): find endpoints/versions supporting a given IO type (string tag like "T2T" or a ModelIOType)

  • get(provider, model): filter endpoints by provider/model

In the project, REGISTERED_ENDPOINTS is pre-populated by registering multiple endpoint classes.

from freegpthub import REGISTERED_ENDPOINTS

print(REGISTERED_ENDPOINTS.listall())

More examples can be found in scripts/clients.