Idempotency

Use the Idempotency-Key header when creating jobs so network retries do not create duplicate work or double-charge credits.

Supported routes

• POST https://api.flikly.ai/api/v1/developer/video-jobs
• POST https://api.flikly.ai/api/v1/developer/split-jobs

Behavior

• Same key + same body — returns the original job (HTTP 201 with the existing resource).
• Same key + different body — returns IDEMPOTENCY_CONFLICT (HTTP 409).
• Keys are optional but recommended for all production job creates.
• Maximum key length: 120 characters. Split jobs also require a safe character set (alphanumeric and ._:/+=-).

Example

curl -s -X POST "https://api.flikly.ai/api/v1/developer/video-jobs" \
  -H "Authorization: Bearer $FLIKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-order-12345-v1" \
  -d '{
    "prompt": "Product demo on a clean white background",
    "duration_seconds": 10,
    "aspect_ratio": "9:16"
  }'

Retry best practices

• Generate one idempotency key per logical operation (order ID, checkout session, etc.).
• Reuse the same key when retrying after timeouts or 5xx responses.
• Never reuse a key for a different prompt, asset, or split configuration.
• On IDEMPOTENCY_CONFLICT, treat it as a client bug — use a new key or fix the payload.