Stories

Stories generate multi-scene illustrated narratives with consistent characters and style. Your AI assistant composes the storyboard and manages the workflow on your behalf.

Because generating multiple scenes takes time, stories use an async workflow.

How it works

Submit a storyboard (JSON with scenes, characters, and style).
Receive HTTP 202 with a job_id and poll_url.
Poll until status is completed or failed.
Download scene images and character references.

CLI usage

depicta story run storyboard.json

The CLI polls automatically (every 3 seconds) and downloads all scene images when done. If the connection drops, resume with:

depicta story status <job_id>

API usage

curl -X POST https://api.depicta.ai/v1/generate/story \
  -H "Authorization: Bearer dpct_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @storyboard.json

import httpx, time

# Submit
resp = httpx.post(
    "https://api.depicta.ai/v1/generate/story",
    headers={"Authorization": "Bearer dpct_YOUR_API_KEY"},
    json=storyboard,
)
job = resp.json()  # {"job_id": "...", "poll_url": "/v1/generate/story/..."}

# Poll
while True:
    status = httpx.get(
        f"https://api.depicta.ai{job['poll_url']}",
        headers={"Authorization": "Bearer dpct_YOUR_API_KEY"},
    ).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(3)

Response (202 Accepted)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "poll_url": "/v1/generate/story/a1b2c3d4-e5f6-7890-abcd-ef0123456789"
}

Poll response (completed)

{
  "id": "a1b2c3d4-...",
  "status": "completed",
  "scenes_completed": 4,
  "scenes_total": 4,
  "result": {
    "scenes": [
      {
        "prompt": "Aria enters the ancient library...",
        "images": {
          "png": "https://images.depicta.ai/...",
          "jpeg": "https://images.depicta.ai/...",
          "webp": "https://images.depicta.ai/..."
        }
      }
    ],
    "characters": [
      {"name": "Aria", "reference_url": "https://images.depicta.ai/..."}
    ]
  }
}