canonical: https://jentic.com/apis/mangii.ai/mangii

# Mangii Headless API

The Mangii Headless API generates illustrated comic stories and single images from text prompts, then lets you extend a story panel by panel. A story starts from a prompt and a style_id, optional identity or reference images keep a character consistent, and each panel can be regenerated or deleted on its own. Generation calls run asynchronously by default and return a job_id you poll until the job succeeds, while separate billing calls report credit balances, per-day usage, and Stripe Checkout links for buying more credits.

## For AI agents

Generate comic stories and images from prompts in a chosen Mangii style, add or regenerate panels, poll generation jobs, and check the credit balance before spending.

## Scope

Does not handle video animation, print fulfilment, or publishing comics to a storefront. Use for generating illustrated stories, panels, and images from prompts only.

## Capabilities

- Start a new illustrated story from a prompt and style_id, with quality set to standard, hd, or ultra
- Continue an existing story with a new panel, reusing identity_panel_id or continuity_panel_id to keep characters consistent
- Regenerate a single panel with a revised prompt without rebuilding the whole story
- Generate a standalone image in any canonical style returned by the styles listing
- Poll an asynchronous generation job by id until its status reaches succeeded or failed
- Read spendable credits (apiPackCredits and packCredits) and per-day usage before queuing more work

## Use cases

### Agent-driven comic creation through Jentic

A creative agent turns a user's idea into a multi-panel comic by calling the Mangii Headless API through Jentic. It lists styles, creates the story with a prompt and style_id, polls the returned job_id until the job succeeds, then appends panels one at a time. Jentic injects the mangii_sk_ bearer key at call time, so the agent never handles the key itself.

Example prompt: Call GET `/v1/styles`, pick a style id, POST `/v1/stories` with prompt 'A robot learns to paint in a rainy city' and that style_id, then poll GET `/v1/jobs/{id}` with the returned job_id until status is succeeded

### Consistent characters across panels

Story tools need the same character to look the same from panel to panel. The continue-story operation accepts identity_panel_id, identity_image, continuity_panel_id, and context_panel_ids, so each new panel can anchor on an earlier one or on a supplied identity photo. This keeps faces and outfits stable while the scene changes.

Example prompt: POST `/v1/stories/{id}/panels` with prompt 'She opens the old door and finds a garden' and identity_panel_id set to the first panel's id, then GET `/v1/stories/{id}/panels` to confirm the new panel was added

### Fixing a single panel

When one frame misses the brief, regenerating it on its own avoids paying to rebuild the story. The regenerate operation takes a revised prompt and the same continuity inputs as a new panel, and unwanted panels can be deleted outright. Credits charged and remaining are returned with each accepted job.

Example prompt: POST `/v1/stories/{id}/panels/{pid}/regenerate` with prompt 'Same scene but at sunset' and quality 'hd', then poll GET `/v1/jobs/{id}` until the regenerated panel is ready

### Credit-aware generation budgeting

Generation spends credits, so an agent should know the balance before queuing hd or ultra work. The credits call returns weeklyCredits, packCredits, apiPackCredits, and spendableCredits, and the usage call returns per-day consumption. When a top-up is needed, the checkout operation returns a Stripe Checkout URL for a human to complete.

Example prompt: Call GET `/v1/credits`, read spendableCredits, and only POST `/v1/images` with quality 'ultra' when the balance covers it; otherwise call GET `/v1/usage` and report the last days of spend

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/stories` | Create a story (async by default) |
| POST | `/v1/stories/{id}/panels` | Continue a story with a new panel |
| POST | `/v1/stories/{id}/panels/{pid}/regenerate` | Regenerate one panel |
| POST | `/v1/images` | Generate a standalone image |
| GET | `/v1/jobs/{id}` | Poll a generation job |
| GET | `/v1/styles` | List canonical styles |
| GET | `/v1/credits` | Read credit balances |

## Key resources

- **Stories** — Create, list, read, retitle, change visibility of, and delete illustrated stories
- **Panels** — List panels in a story, add a new panel, regenerate one panel, or delete it
- **Images** — Generate a standalone image from a prompt and style
- **Jobs** — Poll the status of asynchronous generation work
- **Styles** — List the canonical art styles, excluding experimental ones
- **Billing** — Read credit balances and per-day usage, and open Stripe Checkout for credits or a subscription

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 59 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 39 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 45 / 100
- **View full report:** https://jentic.com/apis/mangii.ai/mangii/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Mangii by hand means handling its mangii_sk_ bearer key, polling asynchronous jobs, and tracking which credit pools a call spends. Through Jentic you install once, import the Mangii Headless API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Mangii puts the story id in the URL path (`/v1/stories/{id}/...`), so a rule can pin your agent to one story and the operations you pick under it. You choose the operations it may call, so destructive ones like story deletion or panel deletion and the checkout calls are not included unless you add them.
- **Credential handling:** Your Mangii key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a comic story' or 'regenerate a panel', and Jentic returns the matching Mangii operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Leonardo.Ai API** — General image generation with model and style controls rather than story-structured panels
- **Ideogram.ai API** — Text-to-image generation known for rendering legible text inside images
- **OpenAI API** — Language models that can draft the scene-by-scene script before panels are generated

## FAQ

### Is there a Mangii MCP server?

You don't need an MCP server to give your agent the Mangii Headless API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are found by intent when needed, so no extra tool definitions sit in the agent's context.

### What authentication does the Mangii Headless API use?

Per its OpenAPI spec, the Mangii Headless API authenticates with a bearer token in the Authorization header, using a key that starts with mangii_sk_. The spec notes that the checkout operations need a key with billing:write scope, which generate-scoped keys lack. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### How do generation jobs work in the Mangii Headless API?

Story, panel, regenerate, and image calls run asynchronously by default and return 202 with a job_id, the credits charged, and a next_step hint. Poll GET `/v1/jobs/{id}` until status moves from queued or running to succeeded or failed. Set async to false in the request body if you want a synchronous response instead.

### Can I limit what my agent is allowed to do with the Mangii Headless API?

Yes. Write a rule that allows only GET `/v1/styles`, POST `/v1/stories`, POST `/v1/stories/{id}/panels`, and GET `/v1/jobs/{id}`, so the agent can make and extend stories and wait for jobs but cannot delete stories or panels or open a checkout session. Every call it makes runs through your own instance.

### What are the rate limits for the Mangii Headless API?

The OpenAPI spec does not state a numeric limit. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, and a throttled call returns 429, so read those headers to pace generation. See https://api.mangii.ai/openapi.json for the current published spec.

### How do I create a comic story with the Mangii Headless API through Jentic?

Add the Mangii Headless API to Jentic One from the directory and store your mangii_sk_ key once. Your agent then searches for 'create a comic story from a prompt', calls POST `/v1/stories` with a prompt and style_id, and polls GET `/v1/jobs/{id}` with the returned job_id. To run it on your own infrastructure, install Jentic One from its GitHub repo.