機能 · ディテール写真

商品ディテール写真API クローズアップ用

要約

Phottaのディテール写真APIは、指定された商品の一領域のクローズアップをレンダリングします。無料の analyze 呼び出しで撮影価値のあるディテールを提案。generate 呼び出しは解像度ティアなしの一律3 creditsです。

  • 所要時間の目安: 20–60 sec
  • Credits: 3 credits
  • 処理方式: 非同期、ポーリング
  • 制限: 600 リクエスト/分
  • 認証: Bearerキー

このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み

POST/api/v1/detail-photos
RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

概要

概要

エンドポイント
POST /api/v1/detail-photos
認証
Bearer APIキー
処理方式
非同期 — ステータスエンドポイントをポーリング
所要時間の目安
20–60 sec
Credits
3 credits
入力制限
1画像あたり最大10 MB、JPEG, PNG, WebP
冪等性
なし

リクエストとレスポンス

リクエスト

RESPONSE=$(curl -s -X POST https://api.photta.app/api/v1/detail-photos \
  -H "Authorization: Bearer $PHOTTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "product_image": "https://cdn.yourstore.com/products/linen-shirt-hero.jpg",
  "detail_label": "collar stitching",
  "detail_description": "Focus on the reinforced double-stitch seam along the collar edge.",
  "framing": "extreme-closeup",
  "source_type": "apparel"
}')
ID=$(echo "$RESPONSE" | jq -r '.data.id')

202 Accepted / Completed

{
  "data": {
    "id": "dtl_9f2c4a71b8e3d605a1f7c2948d3b6e10",
    "status": "processing",
    "detail_label": "collar stitching",
    "framing": "extreme-closeup",
    "credits_used": 3,
    "created_at": "2026-07-30T14:20:00Z"
  },
  "request_id": "req_dtl001"
}

リクエストパラメータ

product_image

型: string必須

The source image — a completed generation's output_url or any product photo. https URL or base64 data URI. JPEG, PNG, WebP; max 10 MB.

detail_label

型: string必須

The area to zoom into, e.g. "collar stitching", "cuff detail", "fabric weave on the chest", "pendant clasp". Max 100 characters.

detail_description

型: string

Extra guidance for the close-up. Max 400 characters.

framing

型: string

How tight the crop is: "extreme-closeup" — the detail fills ~90% of the frame (near-macro); "closeup" — ~70% with some surrounding context; "medium-closeup" — ~50% with body/outfit visible.

= medium-closeup

値: extreme-closeupcloseupmedium-closeup
source_type

型: string

Tunes what is preserved in the close-up.

= apparel

値: appareljewelry

エラー

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 secondsが含まれます
  • 1画像あたり最大10 MB
  • フォーマット: JPEG, PNG, WebP
  • プランごとの同時実行バッチ数: Free 1 · Hobby 2 · Seller 3 · Brand 4 · Studio 6
  • ポーリングのみ — APIはWebhookを送信しません。

撮影価値のあるディテールを問い合わせてから撮影

無料で分析し、ディテールを選択、送信、ポーリング、ダウンロード。

  1. ステップ 1

    APIキーを生成

    ディテール写真は、他のすべてのPhotta機能と同じ認証情報と同じcredit残高を使用します。

  2. ステップ 2

    撮影すべきディテールを問い合わせる

    `product_image` を指定して POST `/api/v1/detail-photos/analyze` を実行します。該当商品に対する推奨の `detail_label`、`detail_description`、`framing` の値が同期的に返され、料金は一切かかりません。

  3. ステップ 3

    クローズアップをPOST送信

    `product_image` と `detail_label` を指定して POST `/api/v1/detail-photos` を実行します。`framing` には `extreme-closeup`、`closeup`、`medium-closeup` のいずれかを設定し、`source_type` には `apparel` または `jewelry` を指定、最大400文字の `detail_description` を追加します。

  4. ステップ 4

    ジョブが完了するまでポーリング

    `data.status` が `completed` または `failed` になるまで、3秒ごとに GET `/api/v1/detail-photos/:id` を実行します。通常20〜60秒で完了します。

  5. ステップ 5

    ダウンロードと永続化

    完了時のレスポンスボディに `output_url` が含まれます。ディテール写真は、PDPギャラリーのメイン写真の隣にそのまま配置できます。

ディテール写真の本番導入前に開発者が確認する質問

ディテール写真APIとは何ですか?

マクロレンズを用いた2回目のスタジオ撮影を行う代わりに、1枚の広角写真から、襟のステッチ、留め具、胸元の織り目といった商品の指定領域のクローズアップをレンダリングするendpointです。

ディテール写真の料金はいくらですか?

一律3 creditsです。このendpointに解像度ティアはなく、ディテールを提案する analyze の呼び出しは無料です。

analyze endpointは何を返しますか?

提案のリストを返します。各項目には `detail_label`、その領域を見せるべき理由を説明する `detail_description`、推奨の `framing` が含まれます。任意の提案をそのまま generate 呼び出しに渡すことができます。

各 framing オプションの寄り具合はどのくらいですか?

`extreme-closeup` はフレームのほぼ全体をディテールで満たし、`closeup` はその周囲のコンテキストを少し残し、`medium-closeup` は周囲の衣服やアイテムの中にディテールを収めます。商品単位ではなく、ディテール単位で選択してください。

生成された画像をソースとして使用できますか?

はい。`product_image` には、生成完了時の `output_url` だけでなく、独自の商品写真を https URL または base64 データ URI として指定できます。

結果はどのようにポーリングすればよいですか?

`data.status` が `completed` または `failed` になるまで、3 秒ごとに GET `/api/v1/detail-photos/:id` を実行します。解析呼び出しは同期処理のため、ポーリングは不要です。

関連機能

このページに記載されている数値はすべて以下に基づきます: Photta APIドキュメント · 確認済み

5分でAPIを試す

Photta APIキーを生成し、上記のcURLスニペットを貼り付ければ、コーヒーが淹れ終わる前に最初のモデル着用画像が手に入ります。

  • 20–60 sec
  • 3 credits
  • 非同期、ポーリング
  • 600 リクエスト/分
  • Bearerキー