lowpoly 将于 2026年10月30日 下线。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

快速开始

首先创建你的 API key

本指南中的每个请求都需要一个 API key。创建密钥只需几秒钟。

创建你的 API key

通过四个步骤,使用 Meshy REST API 制作你的第一个 3D 模型,从创建 API key 到下载模型。


1获取您的 API key

在开发者平台的 API Keys 页面创建一个 API key。离开该页面后您将无法再次查看该密钥,因此请将其妥善保存。在每个请求中,将其作为 Bearer 令牌放在 Authorization 标头中发送。请参阅Authentication。

您需要付费计划才能创建和管理 API key。在免费计划下,您无法创建自己的密钥,Playground 会使用内置密钥进行测试。

在开发者平台中打开 API Keys 页面,然后创建您的密钥


2创建一个 Image to 3D 任务

将一张图片发送给 Image to 3D。如果想改用文本 prompt 或多张照片作为起点,请使用 Text to 3D 或 Multi-Image to 3D。

首先,将你的密钥存储到环境变量中:

Export your key

export MESHY_API_KEY="<your-api-key>"

以下示例均使用这张照片。若要尝试其他图片,请修改 image_url。

Sample fantasy character illustration used as the Image to 3D input in this guide
Sample input

Request

POST
/openapi/v1/image-to-3d
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${MESHY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
  }'

3检查任务状态

任务在后台运行,通常需要几分钟。请持续从同一个 endpoint 获取任务,直到 status 变为 SUCCEEDED、FAILED 或 CANCELED。在以下请求中,将 <task_id> 替换为第 2 步返回的 ID。两次请求之间,请等待 Retry-After 响应头中指定的秒数。

有关典型处理时间以及放弃等待的时间,请参阅任务生命周期。

Request

GET
/openapi/v1/image-to-3d/:id
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
  -H "Authorization: Bearer ${MESHY_API_KEY}"

Response: SUCCEEDED

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "task_error": {
    "message": ""
  }
}

如果任务失败,status 会显示为 FAILED,并且 task_error 会说明原因。请修正输入或创建另一个任务。请参阅 Errors。


4下载你的模型

这些文件位于上一步响应的 model_urls 中。每种格式(GLB、FBX、OBJ、USDZ 和 STL)都有一个在有限时间内有效的签名 URL。你也可以将该 URL 粘贴到浏览器中下载文件。

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
The resulting 3D model generated from the sample fantasy character photo
Your result

整合到一起

这个脚本会创建任务、等待任务完成,并下载模型。

Full script

import axios from 'axios';
import fs from 'fs';

const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';

// 1. Create the task
const { data: created } = await axios.post(
  'https://api.meshy.ai/openapi/v1/image-to-3d',
  { image_url: imageUrl },
  { headers, timeout: 60_000 },
);
const taskId = created.result;

// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
  const { data, headers: resHeaders } = await axios.get(
    `https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
    { headers, timeout: 30_000 },
  );
  task = data;
  if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
  if (Date.now() > deadline) {
    // The task is still running. Check it again later with the same task ID instead of creating a new one.
    throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
  }
  const waitSeconds = Number(resHeaders['retry-after']) || 5;
  await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}

// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
  throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');

探索常见工作流程


后续步骤