cURL · 首饰试穿 API

首饰试穿 API 使用 cURL

一句话总结

导出 PHOTTA_API_KEY,携带文档指定的 JSON body 向 https://api.photta.app/api/v1/api/v1/tryon/jewelry 发送 POST 请求,获取生成任务 ID,然后每隔 3 秒对 /api/v1/tryon/jewelry/{id} 发起 GET 轮询,直到 data.status 为 completed。搭配 jq 提取输出 URL。

  • 常规耗时: 1.5–4 min
  • Credits: 2K 分辨率 5 credits · 4K 分辨率 6 credits
  • 处理方式: 异步,轮询
  • 限制: 600 次请求/分钟
  • 身份验证: Bearer key

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

POST/api/v1/tryon/jewelry
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
  "jewelry_type": "necklace",
  "mannequin_id": "mnk_j9k1l2",
  "background": "soft window light on dark velvet",
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "user_instruction": "Make the pendant 10% smaller."
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

# $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/jewelry/$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'

概览

概览

端点
POST /api/v1/tryon/jewelry
身份验证
Bearer API 密钥
处理方式
异步 — 轮询状态端点
常规耗时
1.5–4 min
Credits
2K 分辨率 5 credits · 4K 分辨率 6 credits
宽高比
3:4 · 1:1 · 4:3 · 9:16 · 16:9
输入限制
单张图片最大 10 MB;支持 JPEG, PNG, WebP
幂等性
否

工作原理

五个终端步骤,除 curl 和 jq 外零额外依赖。

  1. 步骤 1

    注册并生成密钥

    前往 ai.photta.app,打开 Developers 标签页,点击 Generate API key。正式环境密钥以 `photta_live_` 开头。

  2. 步骤 2

    导出密钥环境变量

    在终端配置文件或 `.envrc` 文件中加入 `export PHOTTA_API_KEY="photta_live_xxx"`,后续所有 curl 调用都将自动读取该变量。

    curl --version   # macOS, Linux, WSL and Windows 10+ ship it
    export PHOTTA_API_KEY="photta_live_xxxxx"
  3. 步骤 3

    固定 base URL

    设置 `export PHOTTA_BASE_URL="https://api.photta.app/api/v1"`,让 curl 命令更精简。

    export PHOTTA_BASE_URL="https://api.photta.app/api/v1"
    export AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
  4. 步骤 4

    提交并轮询

    向 `$PHOTTA_BASE_URL/api/v1/tryon/jewelry` 发送 POST 请求获取 ID,然后每 3 秒循环执行一次 `curl $PHOTTA_BASE_URL/api/v1/tryon/jewelry/{id}`。将响应通过管道传给 jq,以便干净利落地提取 `.data.status`。

    RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/tryon/jewelry \
      -H "Authorization: Bearer $PHOTTA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
      "jewelry_image": "https://cdn.yourstore.com/products/gold-necklace.jpg",
      "jewelry_type": "necklace",
      "mannequin_id": "mnk_j9k1l2",
      "background": "soft window light on dark velvet",
      "resolution": "2K",
      "aspect_ratio": "3:4",
      "user_instruction": "Make the pendant 10% smaller."
    }')
    ID=$(echo "$RESPONSE" | jq -r '.data.id')
    
    # $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/jewelry/$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'
  5. 步骤 5

    持久化存储结果

    任务完成后,使用 jq 提取出 `.data.output_url`,并通过 `curl -o` 将字节流写入本地存储——随时可用于下一个流水线步骤。

错误

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.
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

限制

  • 每个 API 密钥每分钟 600 次请求 (固定窗口;各套餐限制相同)
  • 429 响应包含 Retry-After: 30 秒
  • 单张图片最大 10 MB
  • 格式:: JPEG, PNG, WebP
  • 各套餐并发批处理数:: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • 仅支持轮询 — API 不发送 Webhook。

为什么 cURL 仍是验证 API 最快的方式

  • 零安装——各大主流操作系统均内置 cURL
  • 与 jq 配合实现脚本化流水线(CI、cron、shell 钩子)
  • 在将 endpoint 接入代码之前对其进行冒烟测试的最快方法
  • 本页中的每条命令均可直接粘贴至任何 POSIX shell 运行

局限性与不支持的场景

  • 轮询循环会阻塞终端——如需并行 worker 请改用 Node 或 Python
  • 轮询是唯一的完成信号;API 不发送 webhook
  • Windows 命令提示符用户应运行 WSL 或 PowerShell 的 curl.exe

开发者常见问题

是否有 Photta CLI 工具?

目前还没有——但 cURL 加上一个 15 行的 bash 包装脚本就能满足大部分需求。文档优先采用 cURL 示例,因为任何语言都可以运行子进程,而且 shell 是 CI 流水线中的通用语言。

使用该 API 必须用 jq 吗?

并非硬性要求——但在脚本化流水线中配合使用会轻松得多。jq 允许你直接从 JSON 响应中提取 `.data.id`、`.data.status` 和 `.data.output_url`,无需手动解析。在 macOS 上通过 `brew install jq` 安装,在 Debian/Ubuntu 上通过 `apt install jq` 安装。

如何使用 curl 进行身份验证?

在每个请求中添加 `-H "Authorization: Bearer $PHOTTA_API_KEY"`。请将密钥保存在环境变量中,切勿硬编码到提交的脚本里。`curl --oauth2-bearer` 同样有效,但显式声明请求头的写法在文档和日志中更清晰直观。

我可以在生产环境中使用基于 curl 的脚本吗?

对于单次批量回填和 cron 定时任务,完全可以——成千上万的团队都以此方式上线商品目录回填。对于长期运行的应用程序,使用成熟的编程语言通常更合适,因为你能获得完善的错误处理、重试机制和可观测性。本页上的 curl 示例即使在移植到 Node 或 Python 后依然准确,请求体结构完全一致。

如何通过 bash 循环进行轮询?

使用 `for i in $(seq 1 120); do … ; sleep 3; done`,并在循环体中执行状态检查。当 `.data.status` 变为 `completed` 或 `failed` 时跳出循环。本页的代码示例展示了具体模式,包含严格的执行次数上限,防止卡住的任务导致脚本无限挂起。

如何在 curl 中读取错误响应?

使用 `curl -w "\n%{http_code}"` 可在获取 JSON 响应体的同时捕获 HTTP 状态码。根据状态码进行分支处理:402 表示 credits 不足,429 表示达到 rate limit(请遵循 Retry-After 数值),5xx 表示临时服务器错误。错误体中始终包含 `error.code` 和 `error.message` 字段。

五分钟内上手试用 API

生成 Photta API key,粘贴上方的 cURL 代码片段,咖啡还没煮好,你的第一张模特实穿图就已经生成完毕。

  • 1.5–4 min
  • 2K 分辨率 5 credits · 4K 分辨率 6 credits
  • 异步,轮询
  • 600 次请求/分钟
  • Bearer key