{"version":"1.0","service":"Photo AI Studio Agent Fulfillment API","rate_limits":{"paid_operations":{"limit":0,"window_seconds":0,"applies_to":"generate, edit and video are not rate limited. Credits are the only cap on how fast you can spend."},"reads":{"limit":300,"window_seconds":60,"applies_to":"account, predictions and prediction status, per account."},"uploads":{"limit":60,"window_seconds":60,"applies_to":"upload, per account."},"public_endpoints":{"limit":120,"window_seconds":60,"applies_to":"capabilities, themes and the product feed, per IP address."},"failed_requests":{"limit":60,"window_seconds":60,"applies_to":"generate, edit and video requests that consumed no credits, per account."},"failed_authentication":{"limit":60,"window_seconds":60,"applies_to":"requests rejected with 401 or 403, per IP address."}},"auth":{"type":"bearer","headers":{"authorization":"Bearer <COMMERCE_API_TOKEN>","x-buyer-email":"<user-email>"}},"operations":{"generate":{"endpoint":"POST /api/agent/generate","description":"Generate themed or custom AI photos from a selfie","credits_per_image":100,"params":{"images":{"type":"string[]","required":true,"description":"Array of face image CDN URLs (1-9)"},"category":{"type":"string","required":false,"description":"Theme category slug (see GET /api/agent/themes)"},"gender":{"type":"string","required":true,"description":"male | female | groups | pets | product"},"num_images":{"type":"number","required":false,"description":"Variations per theme (1-4, default: 1)"},"type":{"type":"string","required":false,"description":"themed (default) | custom"},"prompt":{"type":"string","required":false,"description":"Custom prompt (required when type=custom)"},"age":{"type":"string","required":false,"description":"Age descriptor (e.g., \"30s\", \"young\")"},"expression":{"type":"string","required":false,"description":"Expression (e.g., \"smiling\", \"serious\")"},"aspect_ratio":{"type":"string","required":false,"description":"1:1 | 2:3 | 3:2 | 16:9 | 9:16"}}},"edit":{"endpoint":"POST /api/agent/edit","description":"Apply AI editing operations to an image","operations":{"remove_background":{"credits":10,"params":["image_url"]},"replace_background":{"credits":3,"params":["image_url","prompt"]},"retouch":{"credits":100,"params":["image_url","prompt"]},"skin":{"credits":100,"params":["image_url"]},"hair":{"credits":100,"params":["image_url","hairstyle"]},"makeup":{"credits":100,"params":["image_url"]},"age":{"credits":100,"params":["image_url","target_age"]},"expression":{"credits":100,"params":["image_url","target_expression"]},"body_type":{"credits":100,"params":["image_url","target_body_type"]},"eye_color":{"credits":100,"params":["image_url","target_eye_color"]},"color_correction":{"credits":100,"params":["image_url"]},"custom":{"credits":100,"params":["image_url","prompt"]},"clothes":{"credits":100,"params":["image_url","clothes_image_url"]},"try_on":{"credits":100,"params":["image_url","clothes_image_url"]},"product":{"credits":100,"params":["image_url","product_image_url"]},"upscale":{"credits":100,"params":["image_url"]},"restore":{"credits":100,"params":["image_url"]},"face_swap":{"credits":100,"params":["source_image_url","target_image_url"]},"extend":{"credits":100,"params":["image_url"]}}},"video":{"endpoint":"POST /api/agent/video","description":"Generate videos from images","operations":{"image_to_video":{"credits":500,"params":["image_url","prompt"]},"ugc":{"credits":500,"params":["image_url","script","voice_id"]},"product_holder":{"credits_video":500,"credits_image":100,"params":["person_image_url","product_image_url"]}}},"upload":{"endpoint":"POST /api/agent/upload","description":"Upload an image by URL or base64. Returns a CDN URL for use in other operations.","accepts":["image_url (string)","image_base64 (data URI or raw base64)"]}},"gallery":{"list":"GET /api/agent/predictions?page=1&limit=20&state=succeeded","status":"GET /api/agent/predictions/:id","account":"GET /api/agent/account"},"polling":{"description":"All generation/edit/video operations return a prediction_id. Poll GET /api/agent/predictions/:id until state is \"succeeded\" or \"failed\".","states":["pending","succeeded","failed"],"recommended_interval_ms":3000}}