快速入门

5 分钟内生成第一张 Photta 图像。

一句话总结

在 ai.photta.app 注册，点击 Generate API key，将其导出为 PHOTTA_API_KEY，向 /api/v1/tryon/apparel 发送 POST 请求，并每 3 秒轮询一次返回的生成 ID，直到状态变为 completed——通常在 1.5 到 4 分钟内完成。

获取 API Key阅读文档
  • 身份验证: Bearer key
  • 处理方式: 异步，轮询
  • 限制: 600 次请求/分钟

本页所有数据均来自 Photta API 文档 · 已验证 

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

工作原理

从零到首张图像的五条命令

按顺序粘贴到终端中运行。每个代码片段均自成一体，仅需使用 curl + jq。

  1. 步骤 1

    生成 API 密钥

    在 ai.photta.app 注册并打开开发者控制台。点击 Generate API key——生产密钥以 photta_live_ 开头。将其导出为环境变量，以便后续教程步骤能直接从 shell 中读取。

    # https://ai.photta.app → Developers → Generate API key
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://api.photta.app/api/v1"

  2. 步骤 2

    POST 提交你的首次 try-on

    携带商品图片 URL 和 mannequin ID 请求 /api/v1/tryon/apparel。API 会立即返回 202 Accepted，并在 data.id 中返回生成 ID。

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/apparel \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "top",
  "product_images": [
    "https://cdn.yourstore.com/products/shirt-front.jpg"
  ],
  "product_back_image": "https://cdn.yourstore.com/products/shirt-back.jpg",
  "product_category": "t_shirt",
  "mannequin_id": "mnk_f3a9b1",
  "pose_id": "pose_c2d4e5",
  "background": "https://cdn.yourstore.com/backgrounds/studio-loft.jpg",
  "lock_background": true,
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "body_size": "M",
  "expression": "neutral",
  "user_instruction": "Keep the collar pattern crisp and centered."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

  3. 步骤 3

    轮询直至完成

    每 3 秒调用一次 GET /api/v1/tryon/apparel/:id。通常耗时 1.5–4 分钟。请为重试次数设置上限，避免卡住的任务导致脚本永久挂起。

    # $ID is data.id from the POST response. Poll every 3 seconds until status is "completed" or "failed".
for i in $(seq 1 120); do
  RESULT=$(curl -s "https://api.photta.app/api/v1/tryon/apparel/$ID" -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "generation failed" && exit 1
  sleep 3
done
echo "$RESULT" | jq -r '.data.output_url'

  4. 步骤 4

    持久化输出结果

    当 status 变为 completed 时，data.output_url 中即包含渲染好的图像。请将文件数据下载至你自己的存储中，避免产品渲染依赖 Photta 的 CDN。

    OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"

  5. 步骤 5

    严谨处理各类异常情况

    根据 HTTP 状态码进行分支处理：402 代表 credits 不足，429 代表触发 rate limit（请遵守 Retry-After），5xx 代表临时服务器错误。每个错误体都包含机器可读的 error.code，便于代码处理。

    case "$STATUS_CODE" in
  402) echo "insufficient_credits_error — top up before retrying" ;;
  429) echo "rate_limit_error — wait the Retry-After seconds (30 by default)" ;;
  4??) echo "$BODY" | jq '.error.type, .error.message' ;;
  5??) echo "api_error — retry with backoff" ;;
esac

开发者常见问题

入门常见问题

快速上手需要多长时间？

注册 + 生成密钥 + 跑通第一个 cURL 仅需 5 分钟。图像生成本身需要 1.5 到 4 分钟，因此从零到看到第一张上身效果图，预计需要 10 分钟整机时间。

试用需要绑定信用卡吗？

新账户自带免费试用 credits，可在付费前直接体验。准备上线生产环境时，订阅相应方案即可获得更高的每月 credit 额度与更宽松的 rate limit。

我应该先尝试哪个 endpoint？

服装 try-on（/api/v1/tryon/apparel）——它是使用最广泛的接口，文档最完整，并且完整涵盖了 Photta 所有其他 endpoint 复用的异步 + polling 模式。熟悉该流程后，珠宝和假人隐形（ghost mannequin）也是完全相同的调用方式。

可以直接在浏览器前端调用吗？

不能。你的 API key 必须保留在服务端——直接打包到浏览器端会导致密钥泄露给所有访问者。请通过你自身后端的轻量代理（Next.js route handler、Express、Flask、Lambda 等）转发请求，让浏览器仅与你的代理通信。

相关页面

本页所有数据均来自 Photta API 文档 · 已验证

距你的第一张生成图仅需 5 分钟

获取 API Key探索 API
  • Bearer key
  • 异步，轮询
  • 600 次请求/分钟