cURL · 虚拟试穿 API

cURL 虚拟试穿 API

理解任何 API 最快的方法就是在 Shell 中调用它。Photta 的文档设计初衷就是 cURL 优先 —— 本页面的所有内容都可以在终端运行,无需 Node 或 Python 环境。

一句话介绍

导出 `PHOTTA_API_KEY`,携带正确的 JSON 请求体向 `https://ai.photta.app/api/v1/tryon/apparel` 发送 POST,获取任务 ID,然后每 3 秒循环运行 `curl … /tryon/apparel/:id` 直至 `data.status` 变为 `completed` —— 通常在 1.5 到 4 分钟内完成。配合 `jq` 即可从最终响应中提取 output URL。

已更新 · 2026-04-19

发起首次请求

cURLNode.jsPythoncURL
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -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"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done

预期效果

Typical completion

1.5–4min

2K / 4K credits

5 / 7

Aspect ratios

5

Product types

6

工作原理

cURL 虚拟试穿 API

五个 Shell 步骤,除 curl 和 jq 外零依赖。

  1. 01

    步骤 1

    注册并生成密钥

    访问 ai.photta.app,打开 Developers 选项卡,点击 Generate API key。生产密钥以 `photta_live_` 开头。

  2. 02

    步骤 2

    导出密钥

    在您的 Shell 配置文件或 `.envrc` 文件中添加 `export PHOTTA_API_KEY="photta_live_xxx"`,这样后续的所有 curl 调用都能自动读取。

  3. 03

    步骤 3

    设置基础 URL 变量

    `export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"` 可以保持 curl 命令简洁,也方便在未来上线沙盒环境时快速切换。

  4. 04

    步骤 4

    提交并轮询

    POST 到 `$PHOTTA_BASE_URL/tryon/apparel` 获取任务 ID,然后循环运行 `curl $PHOTTA_BASE_URL/tryon/apparel/$ID`。将响应传给 jq 以提取 `.data.status`。

  5. 05

    步骤 5

    持久化结果

    任务完成后,使用 jq 提取 `.data.output_url` 并通过 `curl -o` 将字节流下载到本地 —— 即可进入流水线的下一步。

端到端代码

Copy, paste, done.

Four snippets — install prerequisites, wrap the REST call, submit + poll, then handle the errors that actually happen in production.

01cURL is already installed on macOS, Linux, WSL and modern Windows
bash
# Verify curl is available
curl --version

# Export your API key so the rest of the calls can reference it
export PHOTTA_API_KEY="photta_live_xxxxx"
02Set the base URL + auth header once
bash
# Pin the base URL in a shell variable so every call is a one-liner.
export PHOTTA_BASE_URL="https://ai.photta.app/api/v1"

# Reusable auth header — every request needs it.
AUTH_HEADER="Authorization: Bearer $PHOTTA_API_KEY"
03Submit and poll in one script
bash
# Submit a try-on job. The API returns 202 Accepted + a generation ID.
JOB=$(curl -s -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -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"
  }')

ID=$(echo "$JOB" | jq -r '.data.id')
echo "Generation $ID queued"

# Poll every 3 seconds until the job completes (max 6 minutes).
for i in $(seq 1 120); do
  RESULT=$(curl -s "$PHOTTA_BASE_URL/tryon/apparel/$ID" -H "$AUTH_HEADER")
  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  if [ "$STATUS" = "completed" ]; then
    echo "$RESULT" | jq -r '.data.output_url'
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq -r '.data.error_message' >&2
    exit 1
  fi
  sleep 3
done
04Read the status code + error body instead of silently failing
bash
# -w pulls out the HTTP status without polluting the JSON body.
RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$PHOTTA_BASE_URL/tryon/apparel" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{ "product_type": "dress" }')

BODY=$(echo "$RESPONSE" | sed '$d')
STATUS=$(echo "$RESPONSE" | tail -1)

case "$STATUS" in
  200|202)
    echo "$BODY" | jq '.data' ;;
  402)
    echo "Out of credits" ; echo "$BODY" | jq '.error' ;;
  429)
    RETRY=$(echo "$BODY" | jq -r '.error.retry_after')
    echo "Rate limited — retry in ${RETRY}s" ;;
  *)
    echo "Error $STATUS" ; echo "$BODY" | jq '.error' ;;
esac

设计初衷

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

  • Zero install — cURL ships with every major OS
  • Pairs with `jq` for scripted pipelines (CI, cron, bash hooks)
  • Ideal for smoke-testing endpoints before wiring them into code
  • All code in this page copy-pastes into any POSIX shell

功能边界

Honest caveats

  • cURL's polling loop blocks your terminal — move to Node/Python for parallel workers
  • No streaming parser for the result; you fetch the final URL when the job is done
  • Windows Command Prompt users should run WSL or PowerShell's curl.exe wrapper

开发者常见问题

Questions other developers ask

有 Photta CLI 工具吗?+

目前还没有 —— 但 cURL 配合 15 行的 Bash 脚本就能实现大部分功能。文档优先提供 cURL 示例是因为任何编程语言都能运行子进程,且 Shell 是 CI 流水线的公约数。

我需要 jq 才能使用 API 吗?+

非强制 —— 但脚本化流程有了它会轻松很多。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` 也可行,但显式 Header 形式在文档和日志中更清晰。

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

对于一次性的批量回填和 Cron 任务,完全可以 —— 成千上万的团队通过这种方式处理目录回填。对于长期运行的应用,通常建议使用正式编程语言,因为可以获得更好的错误处理、重试逻辑和可观测性。即使迁移到 Node 或 Python,本页面的 curl 示例依然准确,因为请求结构是一致的。

如何通过 Bash 循环进行轮询?+

在循环体中使用 `for i in $(seq 1 120); do … ; sleep 3; done` 进行状态检查。当 `.data.status` 为 `completed` 或 `failed` 时退出循环。本页面的代码示例展示了具体模式,包括硬性的上限,防止脚本因任务卡死而无限运行。

如何通过 curl 读取错误响应?+

使用 `curl -w "\n%{http_code}"` 可以随 JSON 请求体一起捕获 HTTP 状态码。根据状态码进行逻辑分支:402 代表点数不足,429 代表速率限制(需遵循 Retry-After 值),5xx 代表服务器临时错误。错误请求体始终包含 `error.code` 和 `error.message` 字段。

cURL · 虚拟试穿 API

创建账户并获取 API 密钥

导出 `PHOTTA_API_KEY`,携带正确的 JSON 请求体向 `https://ai.photta.app/api/v1/tryon/apparel` 发送 POST,获取任务 ID,然后每 3 秒循环运行 `curl … /tryon/apparel/:id` 直至 `data.status` 变为 `completed` —— 通常在 1.5 到 4 分钟内完成。配合 `jq` 即可从最终响应中提取 output URL。

cURL 虚拟试穿 API — Photta | Photta