S3AI Docs

Appearance

3D 生成 API ​

S3AI 的 3D 生成接口支持文生 3D、图生 3D 和 draft 补 texture。接口会先返回异步任务，客户端需要轮询任务状态，并在任务完成后从响应中取得 GLB 下载地址。

API Path ​

提交生成任务：

http
POST https://ai.furry.vg/v1/3d

轮询任务状态：

http
GET https://ai.furry.vg/v1/3d/{task_id}

下载已完成的 GLB：

http
GET https://ai.furry.vg/v1/3d/{task_id}/content

请求体参数 ​

字段类型必填说明
modelstring是模型名
promptstring条件必填文生 3D 时必填；texture 模式可选，用于补充材质描述。
input_referencestring条件必填图生 3D 时必填，支持 Data URL 或裸 Base64，不支持 HTTP URL。
source_task_idstringtexture 模式必填draft 补 texture 时使用的公开任务 ID。传入已完成 draft 响应里的 id。
metadataobject否额外参数。
metadata.art_stylestring否生成风格，默认 realistic。

模型列表 ​

model 值说明
meshy-6Meshy 6，生成带贴图的模型
meshy-6-draftMeshy 6，仅生成 draft 无贴图模型
meshy-6-textureMeshy 6，对已有 draft 生成贴图
meshy-5.3Meshy 5.3，生成带贴图的模型
meshy-5.3-draftMeshy 5.3，仅生成 draft 无贴图模型
meshy-5.3-textureMeshy 5.3，对已有 draft 生成贴图
meshy-5.1Meshy 5.1，生成带贴图的模型
meshy-5.1-draftMeshy 5.1，仅生成 draft 无贴图模型
meshy-5.1-textureMeshy 5.1，对已有 draft 生成贴图
meshy-5Meshy 5，生成带贴图的模型
meshy-5-draftMeshy 5，仅生成 draft 无贴图模型
meshy-5-textureMeshy 5，对已有 draft 生成贴图
meshy-4Meshy 4，生成带贴图的模型
meshy-4-draftMeshy 4，仅生成 draft 无贴图模型
meshy-4-textureMeshy 4，对已有 draft 生成贴图

art_style 可选值 ​

值说明
realistic写实风格（默认）
cartoon卡通风格
sculpture雕塑风格
pbrPBR 材质风格

input_reference 支持格式 ​

  • Data URL："data:image/png;base64,iVBORw0KGgo..."
  • 裸 Base64："iVBORw0KGgo..."

input_reference 不支持 http:// 或 https:// 图片地址。请先读取图片内容并编码为 Base64，再以 Data URL 或裸 Base64 传入。

提交请求 ​

请求需要携带 API Key：

http
Authorization: Bearer sk-your-s3ai-key
Content-Type: application/json

文生 3D ​

bash
curl -s https://ai.furry.vg/v1/3d \
  -H "Authorization: Bearer sk-your-s3ai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meshy-6",
    "prompt": "a medieval wooden treasure chest with iron bands",
    "metadata": {
      "art_style": "cartoon"
    }
  }'

图生 3D ​

bash
curl -s https://ai.furry.vg/v1/3d \
  -H "Authorization: Bearer sk-your-s3ai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meshy-6",
    "input_reference": "data:image/png;base64,iVBORw0KGgo...",
    "metadata": {
      "art_style": "realistic"
    }
  }'

提交响应 ​

提交成功后会返回公开任务 ID，后续轮询、下载以及 draft 补 texture 都使用这个 ID。

json
{
  "id": "task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp",
  "object": "3d",
  "model": "meshy-6",
  "status": "queued",
  "progress": 0,
  "created_at": 1783495163
}

轮询状态 ​

使用提交响应里的 id 轮询状态：

bash
curl -s https://ai.furry.vg/v1/3d/task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp \
  -H "Authorization: Bearer sk-your-s3ai-key"

处理中响应：

json
{
  "created_at": 1783495163,
  "id": "task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp",
  "model": "meshy-6",
  "object": "3d",
  "progress": 45,
  "status": "in_progress"
}

完成响应：

json
{
  "completed_at": 1783495245,
  "created_at": 1783495163,
  "data": {
    "format": "glb",
    "url": "https://ai.furry.vg/v1/3d/task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp/content"
  },
  "id": "task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp",
  "model": "meshy-6",
  "object": "3d",
  "progress": 100,
  "status": "completed"
}

常见状态：

status说明
queued任务已入队。
in_progress任务处理中，可根据 progress 展示进度。
completed任务完成，可以下载结果。
failed任务失败，检查错误信息或重试。

轮询建议 ​

提交成功后，请使用提交响应中的 id 查询状态。建议每 2 到 5 秒轮询一次，并在客户端设置总等待时间，避免无限轮询。

  • queued 和 in_progress：继续轮询，不要重复提交相同任务。
  • completed：读取 data.url 下载结果。
  • failed：记录公开任务 ID、响应内容和请求时间；修正输入后再提交新任务。
  • 网络超时：优先用已有公开任务 ID 继续查询，而不是立即新建任务。

以下 Shell 示例最多轮询 60 次，每次间隔 3 秒：

bash
task_id="task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp"

for attempt in $(seq 1 60); do
  response=$(curl -sS "https://ai.furry.vg/v1/3d/$task_id" \
    -H "Authorization: Bearer $OPENAI_API_KEY")
  printf '%s\n' "$response"

  case "$response" in
    *'"status":"completed"'*|*'"status": "completed"'*) break ;;
    *'"status":"failed"'*|*'"status": "failed"'*) exit 1 ;;
  esac

  sleep 3
done

下载结果 ​

当 status 为 completed 时，读取 data.url 下载生成的 GLB 文件。

bash
curl -L "https://ai.furry.vg/v1/3d/task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp/content" \
  -H "Authorization: Bearer sk-your-s3ai-key" \
  -o result.glb

完成响应里的字段含义：

字段说明
data.url经过 S3AI 鉴权的 GLB 下载地址。请求时需要携带 API Key。
data.format输出文件格式，当前示例为 glb。
id公开任务 ID，用于状态轮询、下载以及 draft 补 texture。

Draft 补 Texture ​

如果先使用带 -draft 后缀的模型生成 draft，后续补 texture 时直接使用 draft 响应里的公开 id：

json
{
  "data": {
    "format": "glb",
    "url": "https://ai.furry.vg/v1/3d/task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp/content"
  },
  "id": "task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp",
  "object": "3d",
  "model": "meshy-6-draft",
  "status": "completed"
}

然后把这个公开 id 放到下一次请求的顶层 source_task_id：

bash
curl -s https://ai.furry.vg/v1/3d \
  -H "Authorization: Bearer sk-your-s3ai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meshy-6-texture",
    "source_task_id": "task_TGMd3VfQ3TxvBe050uoiNNVYrFGhExlp",
    "metadata": {
      "art_style": "pbr"
    }
  }'

source_task_id 必须属于当前 API Key 对应的用户，并且来源任务必须已经完成、使用同一 Meshy 基础模型且为 draft 模式。S3AI 会在服务端解析上游任务信息，客户端不需要接触任何内部任务 ID。

Powered by VitePress

Copyright © 2026 S3AI