使用 Curl 查询 Gradio 应用程序

Gradio 应用程序可以使用 cURL（许多操作系统预装的命令行工具）作为 API 进行调用。如果您试图从非 Python 或 Javascript 环境查询 Gradio 应用程序，这会特别有用（因为 Gradio 已经为 Python 和 Javascript 提供了专门的客户端）。

例如，考虑这个将英文翻译成法文的 Gradio 演示：https://abidlabs-en2fr.hf.space/。

使用 curl，我们可以通过编程方式翻译文本。

这是实现的代码

$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello, my friend."] 
}'

>> {"event_id": $EVENT_ID}

$ curl -N https://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID

>> event: complete
>> data: ["Bonjour, mon ami."]

注意：进行预测并获取结果需要两个 curl 请求：一个 POST 请求和一个 GET 请求。POST 请求返回一个 EVENT_ID 并将其打印到控制台，然后在第二个 GET 请求中使用该 ID 来获取结果。您可以使用 awk 和 read 将这两个请求合并为一个命令，以便解析第一个命令的结果并将其传递给第二个命令，如下所示

$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello, my friend."] 
}' \
  | awk -F'"' '{ print $4}'  \
  | read EVENT_ID; curl -N https://abidlabs-en2fr.hf.space/call/predict/$EVENT_ID

>> event: complete
>> data: ["Bonjour, mon ami."]

在本指南的其余部分中，我们将更详细地解释这两个步骤，并提供使用 curl 查询 Gradio 应用程序的其他示例。

先决条件：对于本指南，您不需要非常详细地了解如何构建 Gradio 应用程序。但是，对 Gradio 的输入和输出组件概念有大致的了解会很有帮助。

安装

您通常不需要安装 cURL，因为它预装在许多操作系统上。运行

curl --version

来确认 curl 是否已安装。如果尚未安装，您可以访问 https://curl.se/download.html 进行安装。

步骤 0：获取 Gradio 应用程序的 URL

要查询 Gradio 应用程序，您需要其完整的 URL。这通常就是 Gradio 应用程序托管的 URL，例如：https://bec81a83-5b5c-471e.gradio.live

Hugging Face Spaces

但是，如果您要查询 Hugging Face Spaces 上的 Gradio 应用程序，则需要使用嵌入的 Gradio 应用程序的 URL，而不是 Space 网页的 URL。例如

❌ Space URL: https://hugging-face.cn/spaces/abidlabs/en2fr
✅ Gradio app URL: https://abidlabs-en2fr.hf.space/

您可以通过单击页面底部的“view API”（查看 API）链接来获取 Gradio 应用程序的 URL。或者，您可以右键单击页面，然后单击“View Frame Source”（查看框架源代码）或浏览器中的等效选项来查看嵌入的 Gradio 应用程序的 URL。

虽然您可以将任何公共 Space 用作 API，但如果您发出过多请求，可能会受到 Hugging Face 的速率限制。为了无限制地使用 Space，只需复制 Space 创建一个私人 Space，然后随心所欲地发出请求！

注意：要查询私人 Space，您需要传入 Hugging Face (HF) 令牌。您可以在此处获取 HF 令牌：https://hugging-face.cn/settings/tokens。在这种情况下，您需要在下面讨论的两个 curl 调用中都包含一个额外的标头

-H "Authorization: Bearer $HF_TOKEN"

现在，我们准备发出两个 curl 请求。

步骤 1：进行预测（POST）

两个 curl 请求中的第一个是 POST 请求，它将输入有效负载提交给 Gradio 应用程序。

POST 请求的语法如下

$ curl -X POST $URL/call/$API_NAME -H "Content-Type: application/json" -d '{
  "data": $PAYLOAD
}'

其中

$URL 是在步骤 0 中获取的 Gradio 应用程序的 URL
$API_NAME 是您正在运行的事件的 API 端点名称。您可以通过单击页面底部的“view API”（查看 API）链接来获取 API 端点名称。
$PAYLOAD 是一个有效的 JSON 数据列表，其中包含输入有效负载，每个输入组件对应一个元素。

成功发出此 POST 请求后，您将在终端中收到一个事件 ID，格式如下

>> {"event_id": $EVENT_ID}

在随后的 curl 请求中需要此 EVENT_ID 来获取预测结果。

以下是一些如何发出 POST 请求的示例

基本示例

回到页面开头的示例，下面是如何为接受单个输入文本组件的简单 Gradio 应用程序发出 POST 请求

$ curl -X POST https://abidlabs-en2fr.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello, my friend."] 
}'

多个输入组件

这个Gradio 演示接受三个输入：一个对应 gr.Textbox 的字符串，一个对应 gr.Checkbox 的布尔值，以及一个对应 gr.Slider 的数值。这是 POST 请求

curl -X POST https://gradio-hello-world-3.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": ["Hello", true, 5]
}'

私人 Spaces

如前所述，如果您要向私人 Space 发出请求，则需要传入具有对 Space 读取权限的 Hugging Face 令牌。请求如下所示

$ curl -X POST https://private-space.hf.space/call/predict -H "Content-Type: application/json" -H "Authorization: Bearer $HF_TOKEN" -d '{
  "data": ["Hello, my friend."] 
}'

文件

如果您使用 curl 查询需要文件输入的 Gradio 应用程序，则文件必须以 URL 形式提供，并且 URL 需要包含在以下格式的字典中

{"path": $URL}

这是一个 POST 请求示例

$ curl -X POST https://gradio-image-mod.hf.space/call/predict -H "Content-Type: application/json" -d '{
  "data": [{"path": "https://raw.githubusercontent.com/gradio-app/gradio/test/test_files/bus.png"}] 
}'

有状态演示

如果您的 Gradio 演示在多次交互中保留用户状态（例如，是一个聊天机器人），您可以传入一个 session_hash 以及 data。具有相同 session_hash 的请求被假定为属于同一用户会话。这可能如下所示

# These two requests will share a session

curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{
  "data": ["Are you sentient?"],
  "session_hash": "randomsequence1234"
}'

curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{
  "data": ["Really?"],
  "session_hash": "randomsequence1234"
}'

# This request will be treated as a new session

curl -X POST https://gradio-chatinterface-random-response.hf.space/call/chat -H "Content-Type: application/json" -d '{
  "data": ["Are you sentient?"],
  "session_hash": "newsequence5678"
}'

步骤 2：获取结果（GET）

收到对应于预测的 EVENT_ID 后，您可以流式传输结果。Gradio 将这些结果存储在 Gradio 应用程序的最近最少使用缓存中。默认情况下，缓存可以存储 2,000 个结果（跨应用程序的所有用户和端点）。

要流式传输预测结果，请使用以下语法发出 GET 请求

$ curl -N $URL/call/$API_NAME/$EVENT_ID

如果您要从私人 Space 获取结果，请在 GET 请求中包含一个带有 HF 令牌的标头，如下所示：-H "Authorization: Bearer $HF_TOKEN"。

这将生成以下格式的响应流

event: ... 
data: ...
event: ... 
data: ...
...

其中：event 可以是以下之一

generating：表示中间结果
complete：表示预测已完成并给出最终结果
error：表示预测未成功完成
heartbeat：每 15 秒发送一次以保持请求处于活动状态

data 的格式与输入有效负载相同：有效的 JSON 数据列表，其中包含输出结果，每个输出组件对应一个元素。

以下是一些如果请求成功完成您应该期望的结果示例

基本示例

回到页面开头的示例，我们期望结果如下所示

event: complete
data: ["Bonjour, mon ami."]

多个输出

如果您的端点返回多个值，它们将作为 data 列表的元素出现

event: complete
data: ["Good morning Hello. It is 5 degrees today", -15.0]

流式示例

如果您的 Gradio 应用程序流式传输一系列值，那么它们将直接流式传输到您的终端，如下所示

event: generating
data: ["Hello, w!"]
event: generating
data: ["Hello, wo!"]
event: generating
data: ["Hello, wor!"]
event: generating
data: ["Hello, worl!"]
event: generating
data: ["Hello, world!"]
event: complete
data: ["Hello, world!"]

文件示例

如果您的 Gradio 应用程序返回一个文件，该文件将以以下格式的字典表示（可能包括一些额外的键）

{
    "orig_name": "example.jpg",
    "path": "/path/in/server.jpg",
    "url": "https:/example.com/example.jpg",
    "meta": {"_type": "gradio.FileData"}
}

在您的终端中，它可能如下所示

event: complete
data: [{"path": "/tmp/gradio/359933dc8d6cfe1b022f35e2c639e6e42c97a003/image.webp", "url": "https://gradio-image-mod.hf.space/c/file=/tmp/gradio/359933dc8d6cfe1b022f35e2c639e6e42c97a003/image.webp", "size": null, "orig_name": "image.webp", "mime_type": null, "is_stream": false, "meta": {"_type": "gradio.FileData"}}]

身份验证

如果您的 Gradio 应用程序启用了身份验证怎么办？在这种情况下，您需要在使用 cURL 进行任何查询之前，先发出一个额外的 POST 请求进行身份验证。完整的步骤如下

首先，使用 POST 请求提供有效的用户名和密码进行登录

curl -X POST $URL/login \
     -d "username=$USERNAME&password=$PASSWORD" \
     -c cookies.txt

如果凭据正确，您将收到 {"success":true} 响应，并且 cookie 将保存在 cookies.txt 中。

接下来，您需要在发出原始 POST 请求时包含这些 cookie，如下所示

$ curl -X POST $URL/call/$API_NAME -b cookies.txt -H "Content-Type: application/json" -d '{
  "data": $PAYLOAD
}'

最后，您需要 GET 结果，再次提供文件中的 cookie

curl -N $URL/call/$API_NAME/$EVENT_ID -b cookies.txt

入门指南

构建界面

使用 Blocks 构建

附加功能

聊天机器人

数据科学和绘图

流式传输

自定义组件

Gradio 客户端和 Lite

MCP

其他教程

使用 Curl 查询 Gradio 应用程序

安装

步骤 0：获取 Gradio 应用程序的 URL

步骤 1：进行预测（POST）

步骤 2：获取结果（GET）

身份验证