功能 · 眼镜 Studio

眼镜虚拟 try-on API 适用于光学镜与太阳镜

一句话总结

Photta 的眼镜 studio API 可将一张眼镜或太阳镜照片转化为成品效果图。选择纯商品或模特佩戴模式，发送 POST 请求，每 3 秒轮询一次，状态为 completed 时即可下载。2K 分辨率下消耗 5 credits。

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

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

POST/api/v1/eyewear-studio

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "backdrop": "gradient",
    "lighting": "soft",
    "aspect_ratio": "3:4",
    "resolution": "2K"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/eyewear-studio",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
      "mode": "product-only",
      "sub_tool": "studio-shot",
      "backdrop": "gradient",
      "lighting": "soft",
      "aspect_ratio": "3:4",
      "resolution": "2K"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

Sunglasses photographed by the eyewear studio API — 示例输出

概览

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

请求与响应

请求

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/eyewear-studio \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
  "mode": "product-only",
  "sub_tool": "studio-shot",
  "backdrop": "gradient",
  "lighting": "soft",
  "aspect_ratio": "3:4",
  "resolution": "2K"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

const res = await fetch("https://api.photta.app/api/v1/eyewear-studio", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PHOTTA_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "backdrop": "gradient",
    "lighting": "soft",
    "aspect_ratio": "3:4",
    "resolution": "2K"
  }),
});
const { data } = await res.json(); // data.id, data.status

import os, requests

res = requests.post(
    "https://api.photta.app/api/v1/eyewear-studio",
    headers={"Authorization": f"Bearer {os.environ['PHOTTA_API_KEY']}"},
    json={
      "eyewear_image": "https://cdn.yourstore.com/products/aviator-sunglasses.jpg",
      "mode": "product-only",
      "sub_tool": "studio-shot",
      "backdrop": "gradient",
      "lighting": "soft",
      "aspect_ratio": "3:4",
      "resolution": "2K"
    },
)
data = res.json()["data"]  # data["id"], data["status"]

202 Accepted / 已完成

{
  "data": {
    "id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
    "status": "processing",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-08-01T09:15:00Z"
  },
  "request_id": "req_eyw001"
}

{
  "data": {
    "id": "eyw_7a1c9e42f05b3d688c2e4f01a9d6b357",
    "status": "completed",
    "mode": "product-only",
    "sub_tool": "studio-shot",
    "output_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357.jpg",
    "thumbnail_url": "https://cdn.photta.app/generated/eyw_7a1c9e42f05b3d688c2e4f01a9d6b357-thumb.jpg",
    "resolution": "2K",
    "aspect_ratio": "3:4",
    "credits_used": 5,
    "created_at": "2026-08-01T09:15:00Z",
    "completed_at": "2026-08-01T09:15:38Z"
  },
  "request_id": "req_eyw002"
}

请求参数

字段描述

eyewear_image

类型: string必填

The eyewear product image — glasses or sunglasses. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

mode

类型: string

Generation mode: "product-only" — the eyewear alone, styled by sub_tool; "on-model" — the eyewear worn on an AI model's face (requires mannequin_id).

= product-only

product-onlyon-model

sub_tool

类型: string

Product-only styling: "studio-shot" — clean studio product shot; "flat-lay" — top-down arrangement on a surface; "lifestyle" — the eyewear placed in a real-world scene; "floating" — the frames suspended mid-air. Sending sub_tool with mode "on-model" returns 400.

= studio-shot

studio-shotflat-laylifestylefloating

mannequin_id

类型: string

Required when mode is "on-model": the AI model whose face wears the eyewear — an id ("mnk_...") from GET /api/v1/eyewear-studio/mannequins. Sending it in product-only mode returns 400.

face_angle

类型: string

On-model only: the angle of the model's face.

= front

frontthree-quarterside-profile

expression

类型: string

On-model only: the model's facial expression.

= neutral

neutralsoft-smileseriousconfident

lighting_style

类型: string

On-model only: how the portrait is lit.

= soft-diffused

soft-diffusedstudionaturaldramatic

frame_fit_style

类型: string

On-model only: the overall styling of how the frames are worn.

= casual

casualprofessionalfashion-editorialsporty

backdrop

类型: string

Studio-shot only: the backdrop behind the eyewear.

= white

whitegrayblackgradient

lighting

类型: string

Studio-shot only: the lighting setup.

= soft

softharddramaticnatural

surface

类型: string

Flat-lay only: the surface the eyewear lies on.

= marble

marblewoodfabricconcretemetal

arrangement_style

类型: string

Flat-lay only: how the composition is arranged.

= minimal

minimalsymmetricscatteredlayered

props

类型: string

Flat-lay only: complementary props placed around the eyewear.

= none

noneplantsaccessoriestech

scene

类型: string

Lifestyle only: the real-world setting.

= coffee-shop

coffee-shopbeachurban-streetofficepark

mood

类型: string

Lifestyle only: the color mood of the scene.

= warm

warmcoolvibrantmoody

angle

类型: string

Floating only: the camera angle on the suspended frames.

= front

frontthree-quartersidetop-down

shadow_style

类型: string

Floating only: the shadow cast beneath the frames.

= soft-drop

soft-dropnonehard-dropreflection

background_color

类型: string

Solid background color. Applies in both modes. Overridden by background_prompt when both are sent.

= white

whitegrayblackbeige

background_prompt

类型: string

Free-text background description. Max 400 characters — excess is silently truncated. Overrides background_color.

aspect_ratio

类型: string

Output aspect ratio.

= 3:4

3:41:14:39:1616:9

resolution

类型: string

Output resolution. 4K cannot be combined with the 1:1 aspect ratio — that request returns 400.

= 2K

2K4K

错误

状态类型含义

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.

限制

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

输入单张镜框照片，输出成套风格化眼镜图

选择模式，配置该模式提供的样式参数，提交，轮询，下载。

步骤 1
生成 API key
眼镜 studio 与 Photta 的所有其他功能共用相同的凭证和 credit 余额。
步骤 2
选择模式及其样式
`mode` 可选 `product-only` 或 `on-model`。纯商品模式接收 `sub_tool` 参数——包括 `studio-shot`、`flat-lay`、`lifestyle` 或 `floating`——每个子工具都具备专属控制项。模特模式接收 `mannequin_id` 以及 `face_angle`、`expression`、`lighting_style` 和 `frame_fit_style`。
步骤 3
POST 提交眼镜任务
携带 `eyewear_image` 和样式字段向 `/api/v1/eyewear-studio` 发起 POST 请求。`background_prompt` 最多支持 400 个字符，并会覆盖 `background_color`。轮询是唯一的完成信号——该 API 不发送 webhook。
步骤 4
轮询直至任务完成
每 3 秒 GET 一次 `/api/v1/eyewear-studio/:id`，直到 `data.status` 变为 `completed` 或 `failed`；通常需要 20 到 60 秒完成。
步骤 5
下载并持久化保存
任务完成时的响应体包含 `output_url` 和缩略图。请自行转存该文件——此 URL 仅作为单次任务交付使用，并非持久托管服务。

Node.js、Python 和 cURL 中的相同 endpoint

开发者上线眼镜渲染前常问的问题

眼镜 studio API 有什么作用？

它接收一张眼镜或太阳镜的产品照片，并返回一张风格化摄影成品——既可以是单独展示镜框的棚拍、平铺、生活化或悬浮效果，也可以佩戴在你选择的 AI 模特面部。

生成一张眼镜效果图需要多少费用？

2K 分辨率下为 5 credits，4K 分辨率下为 6 credits，与服装和珠宝 try-on 相同。失败的任务会自动退款。

纯商品模式和模特佩戴模式有什么区别？

`product-only` 拍摄镜框单体，由 `sub_tool` 驱动。`on-model` 将镜框佩戴在 AI 模特的脸上，由 `mannequin_id`、`face_angle`、`expression`、`lighting_style` 和 `frame_fit_style` 驱动。属于另一模式的字段将被直接忽略。

各个子工具分别提供哪些样式选项？

`studio-shot` 接收 `backdrop` 和 `lighting`。`flat-lay` 接收 `surface`、`arrangement_style` 和 `props`。`lifestyle` 接收 `scene` 和 `mood`。`floating` 接收 `angle` 和 `shadow_style`。所有这些字段均为枚举类型（enum），传入非预期值会被直接拒绝，而不会进行猜测猜测适配。

我可以使用自己的 AI 模型吗？

可以。`mannequin_id` 接受来自 GET `/api/v1/eyewear-studio/mannequins` 的任意模特 ID，通过模特生成 API 构建的模特也以同样方式使用。

如何轮询获取结果？

每 3 秒调用一次 GET `/api/v1/eyewear-studio/:id`，直到 `data.status` 变为 `completed` 或 `failed`。没有 webhook；轮询是文档规定的完成信号。

五分钟内上手试用 API

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

创建账户并获取 API Key 阅读文档

20–60 sec
2K 分辨率 5 credits · 4K 分辨率 6 credits
异步，轮询
600 次请求/分钟
Bearer key

眼镜虚拟 try-on API 适用于光学镜与太阳镜

概览

请求与响应

请求参数

错误

输入单张镜框照片，输出成套风格化眼镜图

生成 API key

选择模式及其样式

POST 提交眼镜任务

轮询直至任务完成

下载并持久化保存

Node.js、Python 和 cURL 中的相同 endpoint

开发者上线眼镜渲染前常问的问题

相关功能

五分钟内上手试用 API