ZikeeAIをECスタックに統合する：開発者ガイド

<h2>Overview</h2><p>Zikee AI's API is designed for straightforward integration into existing e-commerce workflows. Whether you're building a custom integration with your platform, automating content production at scale, or embedding AI visual tools directly into your product management system, the API provides the building blocks you need.</p><p>This guide covers the essentials: authentication, the key endpoints you'll use most, handling asynchronous jobs, and best practices for production deployments.</p><h2>Authentication</h2><p>All API requests require an API key passed in the Authorization header:</p><pre><code>Authorization: Bearer YOUR_API_KEY</code></pre><p>API keys are generated from your Zikee AI dashboard under Settings → API Keys. We recommend creating separate keys for development and production environments, and rotating keys regularly.</p><p>Never expose your API key in client-side code. All Zikee AI API calls should be made from your backend.</p><h2>Core Endpoints</h2><h3>Virtual Try-On</h3><p>The virtual try-on endpoint takes a garment image and a model image and returns a composite:</p><pre><code>POST /v1/virtual-tryon { "garment_url": "https://...", "model_url": "https://...", "output_format": "jpeg", "quality": 90 }</code></pre><p>The response includes a job ID for async processing. Poll the job status endpoint or use webhooks to receive the result.</p><h3>Video Object Removal</h3><p>Submit a video for object removal processing:</p><pre><code>POST /v1/video/object-removal { "video_url": "https://...", "mask_type": "auto", "objects": ["background", "props"] }</code></pre><p>Video processing is always asynchronous. Use webhooks for production integrations to avoid polling overhead.</p><h3>Image Translation</h3><p>Translate text embedded in product images:</p><pre><code>POST /v1/image/translate { "image_url": "https://...", "source_language": "zh", "target_language": "en", "preserve_layout": true }</code></pre><h2>Handling Asynchronous Jobs</h2><p>Most Zikee AI operations are asynchronous — they return a job ID immediately and process in the background. There are two ways to receive results:</p><h3>Polling</h3><p>Check job status by calling the jobs endpoint with your job ID:</p><pre><code>GET /v1/jobs/{job_id}</code></pre><p>The response includes a status field (pending, processing, completed, failed) and, when complete, the output URLs. Polling is suitable for low-volume integrations or development environments.</p><h3>Webhooks (Recommended for Production)</h3><p>Configure a webhook endpoint in your Zikee AI dashboard. When a job completes, Zikee AI will POST the result to your endpoint:</p><pre><code>{ "event": "job.completed", "job_id": "job_abc123", "status": "completed", "output": { "url": "https://cdn.zikee.ai/output/...", "format": "jpeg", "width": 1200, "height": 1600 } }</code></pre><p>Always verify webhook signatures to ensure requests are genuinely from Zikee AI. The signature is included in the X-Zikee-Signature header.</p><h2>Rate Limits and Quotas</h2><p>API rate limits depend on your plan tier. The default limits are:</p><ul><li>100 requests per minute for image endpoints</li><li>20 requests per minute for video endpoints</li><li>Burst allowance of 2x the per-minute limit for up to 10 seconds</li></ul><p>If you exceed rate limits, the API returns a 429 status with a Retry-After header indicating when you can resume. Implement exponential backoff in your integration to handle rate limit responses gracefully.</p><h2>Production Best Practices</h2><h3>Store Output URLs Promptly</h3><p>Zikee AI output files are stored for 7 days by default. Download and store outputs in your own infrastructure promptly after job completion — don't rely on Zikee AI CDN URLs as permanent storage.</p><h3>Implement Idempotency</h3><p>Use the idempotency key header to safely retry failed requests without creating duplicate jobs:</p><pre><code>Idempotency-Key: your-unique-request-id</code></pre><h3>Handle Errors Gracefully</h3><p>The API uses standard HTTP status codes. Implement proper error handling for 4xx (client errors) and 5xx (server errors) responses. For 5xx errors, retry with exponential backoff. For 4xx errors, inspect the error response body for details before retrying.</p><h3>Use Batch Endpoints for High Volume</h3><p>For catalog-scale processing, use the batch endpoints to submit multiple jobs in a single request. This reduces API call overhead and improves throughput.</p><h2>SDK Support</h2><p>Official SDKs are available for:</p><ul><li><strong>Python</strong> — <code>pip install zikee-ai</code></li><li><strong>Node.js</strong> — <code>npm install @zikee/ai</code></li><li><strong>PHP</strong> — <code>composer require zikee/ai-sdk</code></li></ul><p>The SDKs handle authentication, request signing, webhook verification, and retry logic out of the box. We recommend using an SDK rather than calling the REST API directly for production integrations.</p><h2>Getting Help</h2><p>The Zikee AI developer documentation is available at docs.zikee.ai. For integration support, join the developer community on Discord at discord.gg/zikee or contact the developer support team at [email protected].</p>