Hello 3D

Hello3D Remote MCP

在 ChatGPT 和 Codex 中连接 Hello3D MCP

支持文字、公开 HTTPS 图片链接及兼容客户端的图片附件生成 3D 模型,查询任务并获取临时 GLB 下载链接。通过 ChatGPT 网页 OAuth 或 Codex CLI API Key 接入。

MCPhttps://hello3d.ai/api/mcp
创建 API Key
3 步完成对话式 3D 生成演示查看真实生成的 GLB 模型样例
01 · PROMPTcreate_model

“@Hello3D 生成一只圆滚滚的卡通小狐狸 3D 模型”

支持文生 3D(10–20 积分)或公开 HTTPS 图生 3D(20–30 积分)

02 · POLL STATUSget_model_task

status: "queued" → "success" (100%)

自动同步云端进度,若生成失败自动退还积分

03 · DOWNLOAD GLBget_model_download

fox.glb · signed URL (300s TTL)

直接下载带纹理 GLB,或进入工作台导出 STL / 3MF / FBX

接入方式选择

客户端 / 模式认证方式单次积分消耗状态与输入说明
ChatGPT 网页端OAuth 2.1 (CIMD)文生 20 积分 / 图生 30 积分无需 API Key,网页登录授权后输入 @Hello3D 调用(已上线验证)
Codex CLIBearer API Key文生 20 积分 / 图生 30 积分读取环境变量 HELLO3D_API_KEY(已验证工具发现与查询,生模测试中)

两种连接方式共用同一个远程 MCP 地址与你自己的 Hello3D 账号积分余额。实际价格以 Hello3D 网站当前计费规则为准。

本服务为异步生成接口。提交 create_model 成功后返回 task.id,请通过 get_model_task 查询进度;状态变为 success 后调用 get_model_download 获取 5 分钟有效的 GLB 下载链接。

Hello3D 尚未在 OpenAI 公共插件目录上架。本教程介绍手动连接,适合愿意尝试的用户。ChatGPT 的自定义 MCP 入口是否可用,取决于账号、工作区权限和 OpenAI 当前开放情况。

准备工作

  1. 1注册或登录 Hello3D(https://hello3d.ai/),确认账号内有足够的可用积分。
  2. 2准备能使用 ChatGPT 或 Codex 的账号和设备。模型生成是实际操作,会消耗积分。
  3. 3ChatGPT 网页端可尝试直接上传 PNG、JPEG 或 WebP 附件,也可使用公开 HTTPS 图片链接;附件支持取决于客户端。Codex 桌面端直接上传仍在测试,尚未上线。
OAUTH

ChatGPT:网页登录授权

在 ChatGPT 网页端添加自定义 MCP 服务器并通过 OAuth 授权,全程无需创建或粘贴 API Key。

配置项填写值说明
名称 (Name)Hello3D连接后在对话中通过 @Hello3D 呼出插件
服务器 URLhttps://hello3d.ai/api/mcp连接方式选择使用服务器 URL (Streamable HTTP)
认证方式 (Auth)OAuth跳转到 Hello3D 网页端登录你自己的账号授权
客户端注册方式CIMD如界面出现该选项请选择 CIMD;不要选无认证,也无需填 API Key
  1. 1在浏览器中登录 ChatGPT,打开“插件 / Plugins”页面。选择右上角“添加”或加号,再选择“添加自定义 MCP 服务器 / Add custom MCP server”(页面名称可能随版本调整)。
  2. 2名称填写 Hello3D,服务器 URL 填写 https://hello3d.ai/api/mcp。连接方式使用服务器 URL,认证方式选择 OAuth。
  3. 3如果界面要求选择客户端注册方式,选择 CIMD;不需要填写 Hello3D API Key,也不要选择无认证。如果页面没有该选项,按页面的 OAuth 流程继续。
  4. 4阅读页面提示并创建插件。出现“连接 Hello3D”后继续,在 Hello3D 页面登录你自己的账号,核对授权信息并授权。不要在聊天框中粘贴密码或 API Key。
  5. 5在个人插件中找到并安装 Hello3D;新建对话,输入 @Hello3D 选择它。如果找不到入口,请检查账号功能和工作区管理员权限。
对话调用示例

使用 Hello3D 根据文字“一只圆滚滚的卡通小狐狸”生成一个 3D 模型。生成前告诉我会使用 Hello3D 积分;完成后查询任务并给我下载链接。

图片示例:上传图片后输入“使用 Hello3D 将我刚上传的图片生成 3D 模型,完成后提供下载链接”。附件支持取决于客户端;不支持时可使用公开 HTTPS 图片链接。免费账号的作品可能进入公开审核。下载链接有效期为 5 分钟,过期后可重新获取,请勿公开分享。

CLI

Codex CLI:使用 Hello3D API Key

面向命令行用户。服务器支持 API Key 认证;以下命令基于 Codex CLI 的远程 MCP 和环境变量配置方式。

验证状态说明:独立 Codex CLI 会话已通过 API Key 连接线上服务器、识别三个工具,并成功查询已有任务;该直接连接尚未完成生成和下载的端到端验证,建议先作为小范围测试使用。

1. 创建自己的 API Key

登录 Hello3D API Keys 设置页,点击“创建密钥 / Create Key”,填写名称(例如 Codex)。创建后请立即复制或手动保存窗口中显示的完整密钥,关闭后列表只显示前缀。每个人应使用自己的密钥,不要发送到聊天、截图或提交到代码仓库。

前往 Hello3D API Keys 设置 →

2. 在终端中配置

macOS (zsh / bash) 与 Linux (bash)
printf 'Paste your Hello3D API key (input is hidden): '
read -rs HELLO3D_API_KEY
printf '\n'
export HELLO3D_API_KEY
codex mcp add hello3d_remote \
  --url https://hello3d.ai/api/mcp \
  --bearer-token-env-var HELLO3D_API_KEY
codex mcp list

运行第二行后粘贴刚复制的密钥并按 Enter;输入不会显示。codex mcp list 应列出 hello3d_remote。若该名称已经存在,请先用 codex mcp get hello3d_remote 检查;如需替换自己的旧配置,再运行 codex mcp remove hello3d_remote 后重新添加。

Windows (PowerShell 7)
$env:HELLO3D_API_KEY = Read-Host 'Paste your Hello3D API key' -MaskInput
codex mcp add hello3d_remote `
  --url https://hello3d.ai/api/mcp `
  --bearer-token-env-var HELLO3D_API_KEY
codex mcp list

这些命令配置的是环境变量名称(HELLO3D_API_KEY),不是把密钥写进 MCP 配置。密钥只在当前终端进程及其子进程中可用;关闭终端后,在新终端再次执行输入密钥和设置环境变量的步骤,然后从同一终端运行 codex,无需重复添加服务器。不要在命令中直接写密钥,以免进入终端历史。

桌面应用从图标启动时通常不会继承刚才终端里的变量,因此这套命令不能保证桌面应用可用;请先使用同一终端启动的 Codex CLI。不要假定 ChatGPT 的网页登录授权可直接用于 Codex:该方式尚未完成验证。

3. 生成和下载

在同一个终端运行 codex,开启新会话,并输入:

使用 hello3d_remote 创建一个可爱的卡通小狐狸 3D 模型。完成后查询任务,并把模型下载到当前工作目录中的 fox.glb。生成会消耗 Hello3D 积分,请在提交前先告诉我。

按照 Codex 的权限提示操作。下载成功与否取决于当前环境的网络和文件写入权限;也可以让 Codex 提供临时链接,再由你在浏览器中下载。

MCP 工具参考(3 个标准工具)

连接成功后,客户端会自动发现以下三个工具。创建工具通过 UUID 保证幂等,避免网络重试导致重复扣费。

POSTcreate_model— 创建 3D 模型生成任务

提交文字、公开 HTTPS 图片链接或兼容客户端提供的附件创建 Hello3D v3.1 模型。每次新生成必须提供新的 UUID,同一请求重试必须复用相同 request_id 与参数。

参数名类型必填说明
request_idstring (uuid)必填每次生成任务的唯一 UUID;重试同一请求时请复用该 UUID 以防重复扣费
promptstring可选*文字提示词(不超过 2000 字符,与图片二选一或组合提供)
image_urlstring (https)可选*公开可访问的 HTTPS 图片链接(支持 PNG、JPEG、WebP)
image_fileobject可选*兼容客户端提供的图片附件;不要与 image_url 同时使用
is_publicboolean可选默认 true;私密生成需符合条件的付费账号支持
GETget_model_task— 查询 3D 模型任务状态

根据任务 ID 查询生成进度与结果状态。若任务失败会自动同步状态并按网站规则处理积分退还。

参数名类型必填说明
task_idstring必填create_model 返回的 task.id 任务标识符
GETget_model_download— 获取模型临时下载链接

为已完成的模型签发 5 分钟(300 秒)有效的私有 GET 下载链接。链接过期后可再次调用获取新链接。

参数名类型必填说明
task_idstring必填状态为 success 的模型任务 ID

常见问题

没有自定义 MCP 入口

检查是否使用 ChatGPT 网页版,以及账号、套餐和工作区管理员权限是否允许创建自定义插件。

ChatGPT 授权失败

确认地址为上方完整 URL(https://hello3d.ai/api/mcp)、认证为 OAuth,并在可选时使用 CIMD;重新从插件页面发起连接,检查 Hello3D 账号是否能正常登录。

Codex 提示未授权或找不到工具

确认从设置了 HELLO3D_API_KEY 的同一终端启动了新的 Codex 会话,密钥未被删除且账号可用;使用 codex mcp list 检查配置。该命令只证明已配置,并不能证明认证成功。

积分不足或任务失败

登录 Hello3D 查看积分和任务状态;失败与退还以网站实际结果为准。重复提交可能产生新的计费,请先查询已有任务。

下载链接过期

下载链接有效期为 5 分钟,过期后无需重新生成模型,请客户端重新调用 get_model_download 工具生成新链接。

隐私与密钥安全

API Key 是账号凭据;不再使用或怀疑泄露时,在 API Keys 设置页删除该密钥,并为需要的设备重新创建。公开展示和私密生成受账号权限及网站规则限制;免费账号的模型可能进入公开审核。