SDKs & Examples

End-to-end code examples for common U-Gen API workflows in cURL, JavaScript, and Python. Copy and adapt these snippets for your integration.

API Key Required

All examples require an API key. Generate one from Settings → API Keys in the dashboard, or see the API Keys guide.

1. Create a video generation job

Submit a product name, image URL, and configuration to start generating a UGC video. The API returns a job object with a job_id you can use to track progress.

POST /api/v1/jobs

curl -X POST https://api.u-gen.ai/api/v1/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Premium Wireless Headphones",
    "product_image_url": "https://example.com/headphones.jpg",
    "persona_id": "09d3a33a-3eb0-480a-80df-0c64dbf7c98f",
    "video_model": "veo3_fast",
    "segment_count": 3,
    "interaction_mode": "holdable",
    "caption_style": "tiktok_karaoke",
    "music_enabled": true
  }'

2. Poll for job completion

Poll the job endpoint every 10 seconds to check progress. The response includes current_stage and progress_percent. When complete, retrieve the video from final_video_url.

GET /api/v1/jobs/{job_id}

# Poll until job completes (every 10 seconds)
JOB_ID="550e8400-e29b-41d4-a716-446655440000"

curl -X GET "https://api.u-gen.ai/api/v1/jobs/$JOB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Use Webhooks Instead of Polling

For production systems, configure a webhook to receive instant notifications when jobs complete or fail. See step 3 below.

3. Configure a webhook

Set your webhook URL and signing secret. U-Gen will POST to this URL when jobs complete (job.completed) or fail (job.failed). One webhook URL per account.

PUT /api/v1/tenants/me/webhook

# Configure webhook (one URL per account)
curl -X PUT https://api.u-gen.ai/api/v1/tenants/me/webhook \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/webhooks/ugen",
    "webhook_secret": "a7b3c9d2e1f4a8b5c6d7e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1"
  }'

4. Handle webhook events

Verify the X-UGen-Signature header using HMAC-SHA256. The signature covers the timestamp and body: HMAC(secret, timestamp + "." + body).

Webhook handler

# Generate a signing secret:
openssl rand -hex 32

5. Estimate credits before creating a job

Call the estimate endpoint to calculate the credit cost before committing. The response includes a detailed breakdown by component.

POST /api/v1/credits/estimate

curl -X POST https://api.u-gen.ai/api/v1/credits/estimate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "segment_count": 3,
    "model_id": "veo3_fast",
    "variant": "i2v",
    "music_enabled": true,
    "voice_enabled": true
  }'

Common patterns

Error handling

API errors return a nested JSON body: {"error": {"code": "...", "message": "...", "details": {...}}}. Handle 429 (rate limit) with exponential backoff and 402 (insufficient credits) by checking your balance first.

Pagination

Paginated endpoints use page and page_size query parameters. Responses include items, total, page, page_size, and total_pages.

Idempotency

Pass an idempotency_key field in the POST /jobs request body to safely retry without creating duplicate jobs. If omitted, one is generated automatically.