{"version":1,"description":"AI face animation — animate any portrait with a driving video. USDC on Base.","resources":["https://x402puppet.com/api/generate-x402","https://x402puppet.com/api/uploads"],"ownershipProofs":["0x0000000000000000000000008e6af8ed94e87b4402d0272c5d6b0d47f0483e7c0000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000000e4406f52fd0000000000000000000000002b4e26e1f32c7fbf076563ad49a86b69ae0182160000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000fb49b9480000000000000000000000000000000000000000000000000000000000000001bd71e7ae4046dbcd345631a04e70b360434e724d558d4dbce1a1235e0c5dbe8b7e673ff35925f52d6b485ac8fdd324d9e0ee0163e09e8c3f2b7ea44fc4f727450000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002e00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000001700000000000000000000000000000000000000000000000000000000000000016cd4e62c4a6ffd2623fec5a6162e7ea3775c3216f7b4275a96d1e8f808f186a257731fdfbff607bdf32e4bf4e5bf1c118b157f695032fb59370f53f833ceea00000000000000000000000000000000000000000000000000000000000000002506817f31b6ccc1234a424df1fff4840b8ed06f3671ea34bfbfabcb0b04a176ac1d0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000897b2274797065223a22776562617574686e2e676574222c226368616c6c656e6765223a22524978637558484d4a392d494544757a596a73433554425f554759797a55416b764d56346478655f476967222c226f726967696e223a2268747470733a2f2f7465616d732e73706c6974732e6f7267222c2263726f73734f726967696e223a66616c73657d00000000000000000000000000000000000000000000006492649264926492649264926492649264926492649264926492649264926492"],"instructions":"# x402 Puppet API\n\n> AI face animation — animate any portrait with a driving video.\n> Pay per generation with USDC on Base. No API keys required.\n\n## Base URL\n\nhttps://x402puppet.com\n\n## x402 Payment Flow\n\n1. POST to the endpoint without payment headers\n2. Receive 402 response with `PAYMENT-REQUIRED` header (base64-encoded JSON)\n3. Decode the requirements, sign an EIP-712 authorization with your wallet\n4. Retry the POST with `PAYMENT-SIGNATURE` header containing the signed payload (base64-encoded)\n5. Receive the result on success, plus a `PAYMENT-RESPONSE` header with the settlement receipt\n\n## Endpoints\n\n| Route | Method | Cost | Description |\n|-------|--------|------|-------------|\n| /api/generate-x402 | POST | $0.05 USDC | Generate face animation from source image + driving video |\n| /api/uploads | POST | $0.01 USDC | Get a client token for direct file upload to Vercel Blob |\n| /api/uploads/confirm | POST | Free | Confirm an upload and associate the blob URL |\n\n## Network\n\n- Network: Base mainnet (eip155:8453)\n- Asset: USDC\n\n---\n\n## /api/generate-x402\n\nAccepts two input modes. The recommended path is JSON with file URLs. Alternatively, send files directly as multipart/form-data.\n\n### Option A: application/json with file URLs (recommended)\n\nPass any publicly accessible HTTPS URLs for the source image and driving video. You can host files anywhere — e.g. [agentupload.dev](https://agentupload.dev), your own S3 bucket, or via the `/api/uploads` endpoint below.\n\n```json\n{\n  \"source_image_url\": \"https://example.com/photo.jpg\",\n  \"driving_video_url\": \"https://example.com/driving.mp4\",\n  \"flag_relative\": \"true\",\n  \"flag_do_crop\": \"true\",\n  \"flag_pasteback\": \"true\"\n}\n```\n\nURLs must be HTTPS. The `flag_*` fields are optional (all default to `\"true\"`).\n\n### Option B: multipart/form-data (direct file upload)\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| source_image | File (image/*) | Yes | Portrait photo to animate (JPEG, PNG, WebP, max 10MB) |\n| driving_video | File (video/*) | Yes | Video providing the motion (MP4, MOV, WebM, max 50MB) |\n| flag_relative | string (\"true\"/\"false\") | No | Use relative motion transfer (default: \"true\") |\n| flag_do_crop | string (\"true\"/\"false\") | No | Auto-crop face region (default: \"true\") |\n| flag_pasteback | string (\"true\"/\"false\") | No | Paste animation back onto original image (default: \"true\") |\n\n### Output (application/json)\n\n```json\n{\n  \"videoUrl\": \"https://....blob.vercel-storage.com/...\",\n  \"thumbnailUrl\": \"https://....blob.vercel-storage.com/...\",\n  \"videoContentType\": \"video/mp4\",\n  \"thumbnailContentType\": \"image/jpeg\"\n}\n```\n\n`videoUrl` and `thumbnailUrl` are public URLs you can fetch directly.\n\n### Example Flow\n\n```\n# Step 1: POST without payment — get requirements\nPOST /api/generate-x402\nContent-Type: application/json\nBody: { \"source_image_url\": \"https://example.com/photo.jpg\", \"driving_video_url\": \"https://example.com/driving.mp4\" }\n\nResponse: 402 Payment Required\nHeader: PAYMENT-REQUIRED: <base64-encoded PaymentRequired JSON>\n\n# Step 2: Sign payment and retry\nPOST /api/generate-x402\nContent-Type: application/json\nPAYMENT-SIGNATURE: <base64-encoded signed PaymentPayload>\nBody: { \"source_image_url\": \"https://example.com/photo.jpg\", \"driving_video_url\": \"https://example.com/driving.mp4\" }\n\nResponse: 200 OK\nHeader: PAYMENT-RESPONSE: <base64-encoded settlement receipt>\nBody: { \"videoUrl\": \"...\", \"thumbnailUrl\": \"...\", \"videoContentType\": \"video/mp4\", \"thumbnailContentType\": \"image/jpeg\" }\n```\n\n---\n\n## /api/uploads (optional)\n\nIf you don't have your own file hosting, you can upload files to Vercel Blob via this endpoint. This is a three-step flow:\n\n### Step 1: Get upload token (x402-protected, $0.01)\n\n```\nPOST /api/uploads\nContent-Type: application/json\nBody: { \"filename\": \"photo.jpg\", \"contentType\": \"image/jpeg\" }\n\nResponse: 402 → sign and retry with PAYMENT-SIGNATURE\n\nResponse: 200 OK\n{\n  \"uploadId\": \"<uuid>\",\n  \"clientToken\": \"<vercel-blob-client-token>\",\n  \"pathname\": \"uploads/<uuid>/photo.jpg\",\n  \"expiresAt\": \"2025-01-01T00:05:00.000Z\"\n}\n```\n\nAllowed content types: image/jpeg, image/jpg, image/png, image/gif, image/webp, video/mp4, video/webm, video/mov.\nMax size: 10MB for images, 50MB for videos. Token expires in 5 minutes.\n\n### Step 2: Upload file directly to Vercel Blob\n\n```bash\ncurl -X PUT \"https://vercel.com/api/blob/?pathname=uploads/<uuid>/photo.jpg\" \\\n  -H \"authorization: Bearer <clientToken>\" \\\n  -H \"x-content-type: image/jpeg\" \\\n  -H \"x-api-version: 11\" \\\n  --data-binary @photo.jpg\n```\n\nResponse includes `{ \"url\": \"https://....blob.vercel-storage.com/...\" }`.\n\n### Step 3: Confirm upload (free, no payment)\n\n```\nPOST /api/uploads/confirm\nContent-Type: application/json\nBody: { \"uploadId\": \"<uuid>\", \"blobUrl\": \"https://....blob.vercel-storage.com/...\" }\n\nResponse: 200 OK\n{ \"success\": true, \"upload\": { \"id\": \"...\", \"blobUrl\": \"...\", \"filename\": \"...\", \"contentType\": \"...\" } }\n```\n\nThe `blobUrl` from Step 2/3 can then be used as `source_image_url` or `driving_video_url` in `/api/generate-x402`.\n\n---\n\n## Preset Driving Videos\n\nReady-to-use driving videos hosted at the base URL. Fetch these directly — no upload needed, just download and send as the `driving_video` field.\n\n| URL | Description |\n|-----|-------------|\n| /examples/driving/d6.mp4 | Eyebrow dance — rhythmic eyebrow raises and wiggles |\n| /examples/driving/d11.mp4 | Singing/lip-sync — exaggerated mouth movements and head bops |\n| /examples/driving/d12.mp4 | Head dance — side-to-side head swaying with silly expressions |\n| /examples/driving/d14.mp4 | Crazy eye dance — wide dramatic eye movements with a smile |\n\n## Tips for Agents\n\n- Source image should contain a clear face (frontal or slight angle works best)\n- Driving video should be short (2-10 seconds) for best results\n- Generation takes 30-120 seconds depending on video length\n- Results are returned as public URLs — fetch or embed them directly\n- The generate endpoint has a 5-minute timeout\n- If you receive a non-402 error, do NOT retry with payment — investigate the error first\n- The simplest flow: host files on any HTTPS URL (e.g. agentupload.dev) and pass them as JSON body to `/api/generate-x402`\n- You can also use the preset driving videos above — just fetch the URL and include the file in your multipart/form-data request\n"}