快速入门

五分钟内完成首次 Photta 图像生成。

一个账户，一个 API 密钥，五条 Shell 命令。以下步骤完全遵循 Photta 官方文档推荐 —— 无封装、无 SDK、无框架预设。

一句话介绍

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

获取 API 密钥→阅读文档

工作原理

从零到首图仅需五条命令

按顺序粘贴到终端。每个片段都是独立的，仅需使用 curl + jq。

01
步骤 1
生成 API 密钥
在 ai.photta.app 注册并打开开发者控制面板。点击 Generate API key —— 生产密钥以 photta_live_ 开头。将其导出，以便后续操作可以从您的 Shell 中读取它。
```
# Sign up at ai.photta.app, open the Developers dashboard,
# click "Generate API key" and copy it into your env.
export PHOTTA_API_KEY="photta_live_xxxxx"
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"
```

步骤 2

提交首次试穿

向 /api/v1/tryon/apparel 发送包含产品图 URL、模特 ID 和姿势 ID 的请求。API 会立即返回 202 Accepted 并在 data.id 中返回任务 ID。

curl -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_type": "dress",
    "product_images": ["https://example.com/dress.jpg"],
    "mannequin_id": "mnq_athena_ts",
    "pose_id": "pose_standing_front",
    "resolution": "2K",
    "aspect_ratio": "3:4"
  }'
# Response: 202 Accepted + data.id (generation ID)

步骤 3

轮询直至完成

每 3 秒调用一次 /api/v1/tryon/apparel/:id。典型完成时间为 1.5–4 分钟。请设置重试上限，防止脚本无限挂起。

# Loop every 3 seconds until status flips to "completed".
# Typical completion: 1.5–4 minutes. Max 120 attempts = 6 min.
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" \
    -H "Authorization: Bearer $PHOTTA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Job failed" && exit 1
  sleep 3
done

04
步骤 4
持久化输出
当 status 变为 completed 时，data.output_url 中即为渲染后的图片。下载字节流到您自己的存储中，以免渲染时依赖 Photta 的 CDN。
```
# Pull the final URL out of the response and save the bytes.
OUTPUT_URL=$(echo "$RESULT" | jq -r '.data.output_url')
curl -sO "$OUTPUT_URL"
echo "Saved $(basename "$OUTPUT_URL")"
```

步骤 5

如实处理失败模式

根据 HTTP 状态码进行分支处理：402 代表点数不足，429 代表速率限制（遵循 Retry-After），5xx 代表服务器临时错误。每个错误体都包含一个可供程序读取的 error.code。

# Surface the common failure modes honestly.
case "$STATUS_CODE" in
  402) echo "Out of credits — top up at ai.photta.app" ;;
  429) echo "Rate limited — honour Retry-After header" ;;
  4??) echo "Client error: $(echo "$BODY" | jq '.error.message')" ;;
  5??) echo "Server error — retry with backoff" ;;
esac

开发者常见问题

关于入门的常见问题

快速入门需要多长时间？+

我需要信用卡才能试用吗？+

新账户自带试用点数，无需付费即可测试。准备正式上线时，请订阅相关方案以获得更高的月度点数和更高速率限制。

我应该先尝试哪个端点？+

服装试穿 (/api/v1/tryon/apparel) —— 它是最常用的，文档最齐全，并且涵盖了所有 Photta 端点通用的异步 + 轮询模式。熟悉后，珠宝和隐形模特的集成方式完全相同。

我可以在浏览器中直接运行它吗？+

不行。您的 API 密钥必须保存在服务器端 —— 在浏览器中暴露会导致任何访问者都能窃取它。请通过您自己的后端代理调用（如 Next.js route handler, Express, Flask, Lambda），让浏览器与您的代理通信。

快速入门

离您的第一张 AI 照片仅有五分钟距离

获取 API 密钥 →探索 API