Generations (REST)

This is the REST API for generations — the non-MCP way to drive Figgshield from your own tools and scripts. In Claude or the Claude Code CLI you would use the MCP tools (generate_video, generate_image) instead; both paths run the same models against the same credit balance.

A generation is one video or image job. The lifecycle is asynchronous: you create a job, it moves through queued → running, and it ends as succeeded (with an output_url) or failed (credits refunded automatically).

The generation object

{
  "uuid": "0b8f6a2e-4c1d-4f7a-9b2e-6d3c8a1f5e90",
  "model": "kling-3",
  "model_name": "Kling 3",
  "kind": "video",
  "prompt": "A slow dolly shot across a quiet harbour at dawn",
  "params": { "duration": 5, "resolution": "720p", "audio": false, "aspect_ratio": "16:9" },
  "status": "succeeded",
  "output_url": "https://cdn.figgshield.ai/outputs/0b8f6a2e.mp4",
  "thumbnail_url": "https://cdn.figgshield.ai/thumbs/0b8f6a2e.jpg",
  "credits_charged": 35,
  "error_message": null,
  "created_at": "2026-07-06T09:00:00Z",
  "completed_at": "2026-07-06T09:00:48Z",
  "duration_ms": 48000,
  "is_watermarked": false
}

status is one of queued, running, succeeded, failed. output_url and thumbnail_url are null until the job succeeds; error_message is set only on failure. is_watermarked is always false — outputs are never watermarked.

Outputs expire — download them before they do. output_url and thumbnail_url point to media that Figgshield hosts on a content-delivery link (cdn.figgshield.ai) for up to 7 days after a job finishes, then permanently deletes; once deleted, the media can’t be retrieved. The link is an unguessable, unlisted address, so anyone you share it with can open the media until it expires. The generation record (prompt, params, status, credits) is retained as metadata, but the file behind the link is not kept beyond 7 days — Figgshield is not a durable media library. Save the output when it succeeds. Through an MCP client this happens for you: the tool result hands the file back to your app, which is where your generations should live long-term.

Create a generation

POST /api/generations/create/

# Kling 3 video
curl https://api.figgshield.ai/api/generations/create/ \
  -X POST \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3",
    "prompt": "A slow dolly shot across a quiet harbour at dawn",
    "params": { "duration": 5, "resolution": "720p", "audio": false }
  }'

# Nano Banana 2 image
curl https://api.figgshield.ai/api/generations/create/ \
  -X POST \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A paper boat on a still pond, top-down",
    "params": { "resolution": "2K" }
  }'

Returns 201 with the new generation (status: "queued").

Request body

Field	Type	Notes
model	string	A model slug — e.g. kling-3, kling-3-turbo, seedance-2 or nano-banana-2 (from GET /api/models/).
prompt	string	What to generate.
params	object	Optional settings; allowed keys and values depend on the model’s params_schema — see below.

Params by model

Param	Applies to	Example	Notes
duration	video models	5	5 or 10 seconds. A longer clip costs more.
resolution	video models	"720p"	Allowed values depend on the model (e.g. Kling 3: 720p/1080p/4k; Seedance 2: 480p/720p/1080p).
audio	video models (where supported)	false	Default off; enabling it increases the cost on models that support audio (e.g. Kling 3).
resolution	Nano Banana 2	"2K"	1K, 2K or 4K.
aspect_ratio	most models	"16:9"	Optional, where the model’s params_schema lists it.

Omitted params fall back to defaults. A value outside the model’s schema returns 400 validation_error. The exact allowed values and their credit costs are in each model’s params_schema and pricing — see GET /api/models/ or get_model_pricing.

Credits: pre-flight check, charge, refund

• The credit cost is checked before dispatch. If your balance cannot cover it, the request fails with 402 insufficient_credits and nothing is charged. The exact cost depends on the model and the options you chose — quote it first with get_model_pricing or the model’s pricing array.
• With automatic top-ups enabled, the top-up runs first and the pre-flight check happens after it.
• On success the cost is recorded as credits_charged and appears in the ledger as a burn.
• If the job fails, the charged credits are refunded automatically (ledger entry refund). You only pay for output.

Error responses

Status	Code	Meaning
400	validation_error	Unknown model slug, bad prompt, or params outside the model’s schema.
402	insufficient_credits	Balance cannot cover the cost (after any automatic top-up attempt).
402	subscription_required	The account has no active subscription.
409	parallel_limit_reached	As many jobs already in flight as your plan allows — wait for one to finish.
503	model_unavailable	The model is offline or its provider is not responding. Retry later.

See Errors for the full envelope and handling advice.

Poll a generation

GET /api/generations/{uuid}/ — the polling endpoint. Reading it refreshes the job’s provider status; the backend throttles provider polls to at most one per 2 seconds per job, so poll at a 2-second interval or slower.

while true; do
  BODY=$(curl -s "https://api.figgshield.ai/api/generations/$GENERATION_UUID/" \
    -H "Authorization: Bearer $FIGGSHIELD_API_KEY")
  STATUS=$(echo "$BODY" | jq -r .status)
  [ "$STATUS" = "succeeded" ] && { echo "$BODY" | jq -r .output_url; break; }
  [ "$STATUS" = "failed" ]    && { echo "$BODY" | jq -r .error_message >&2; exit 1; }
  sleep 2
done

Video clips typically take tens of seconds; Nano Banana 2 images usually finish in seconds.

List generations

GET /api/generations/ — your own generations, newest first (-created_at), in the standard list envelope. Page through with ?page=N.

curl "https://api.figgshield.ai/api/generations/?page=1" \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"

Delete a generation

DELETE /api/generations/{uuid}/ — soft delete; the generation disappears from your list. Deleting does not refund credits (only failure does).

curl https://api.figgshield.ai/api/generations/$GENERATION_UUID/ \
  -X DELETE \
  -H "Authorization: Bearer $FIGGSHIELD_API_KEY"

Returns 204 No Content.