Idempotency

The header

Send Idempotency-Key with POST /v1/video/generations: 1–128 letters, digits, ., _, : or -. Use one key per intended generation, such as your own job ID.

curl

curl https://loopling.ai/v1/video/generations \
  -H "Authorization: Bearer $LOOPLING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: job-8812-lantern" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A paper lantern drifting over a night harbour, slow dolly in",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 5
  }'

Node

const res = await fetch('https://loopling.ai/v1/video/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LOOPLING_API_KEY}`,
    'Content-Type': 'application/json',
    // Same key on every retry of this job: one hold, one render.
    'Idempotency-Key': 'job-8812-lantern',
  },
  body: JSON.stringify({
    model: 'seedance-2.5',
    prompt: 'A paper lantern drifting over a night harbour, slow dolly in',
    aspect_ratio: '16:9',
    resolution: '1080p',
    duration: 5,
  }),
})
const replayed = res.headers.get('Idempotent-Replayed') === 'true'

Python

import os, requests

res = requests.post(
    "https://loopling.ai/v1/video/generations",
    headers={
        "Authorization": f"Bearer {os.environ['LOOPLING_API_KEY']}",
        # Same key on every retry of this job: one hold, one render.
        "Idempotency-Key": "job-8812-lantern",
    },
    json={
        "model": "seedance-2.5",
        "prompt": "A paper lantern drifting over a night harbour, slow dolly in",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
        "duration": 5,
    },
)
replayed = res.headers.get("Idempotent-Replayed") == "true"

Replays

A submit with a key you've already used returns 202 with the generation that key started, as it is now, and Idempotent-Replayed: true. Nothing new is held or rendered.

The body is still checked first: a malformed body answers 400. A different valid body under a used key returns the first generation, not an error.

Scope

• Idempotency keys belong to the API key that sends them. The same value from another API key starts a new generation.
• They never expire: a used value replays for the life of its API key.
• A submit refused with a 4xx stores nothing. Resend it with the same key.
• Once a generation exists, its key stays bound to it, even if it fails. Use a new key to try again.
• A 502 provider_error, or a 503 provider_unavailable saying the generation couldn't be admitted, comes after the hold: a failed generation already exists under the key, though you never saw its id. Resending with that key replays the failure, so retry with a new one. See Retries.

Errors

A malformed header answers 400 invalid_idempotency_key. The header is checked before the body's fields.

loopling.ai · grows with you, grows itself

hello@loopling.ai · for agents · community · pricing · Enterprise · API · privacy · terms