Skip to main content

Frequently Asked Questions

Account & Authentication​

How do I create an account?​

Visit app.napkin.ai and sign up for a free account. Once registered, you can access the API by creating an API token in your account settings.

How do I get an API token?​

  1. Log in to your account at app.napkin.ai
  2. Go to your Account Settings (or Team Space Settings if you have Team Space enabled)
  3. Open the Developers tab
  4. Click Create new API token

Keep your API token secure and never share it publicly.

Can I have multiple API tokens?​

Yes, you can create multiple API tokens. This is useful for separating access between different applications or environments.

What happens if my API token is compromised?​

You can revoke any API token at any time from your Account Settings. Once revoked, the token will immediately stop working. Create a new token to continue using the API.

Credits & Pricing​

How does API pricing work?​

API usage consumes credits from your Napkin account—the same credits used by the app. Each visual generation request deducts credits based on your plan.

How can I check my remaining credits?​

You can view your credit balance in your Account Settings at app.napkin.ai.

What happens when I run out of credits?​

When you run out of credits, API requests will fail with a no_credits error. You have several options:

  • Upgrade your plan: Get more monthly credits by upgrading to a higher tier
  • Top up credits: Purchase additional credits without changing your plan
  • Wait for refresh: Credits refresh based on your billing cycle

For high-volume needs, contact us to discuss custom plans.

Are there different pricing tiers?​

Yes, Napkin offers different subscription plans with varying credit allocations. Visit app.napkin.ai to view available plans and pricing.

Making API Requests​

How do I send a request to generate visuals?​

See the Create Visual Request documentation for complete details on how to submit requests.

How do I check the status of my request?​

Visual generation is asynchronous. After submitting a request, poll the status endpoint using the request ID. See the Get Visual Request Status documentation for details.

How long does it take to generate visuals?​

Most requests complete within 10-30 seconds, depending on complexity and server load. Poll the status endpoint to check when your visuals are ready.

What formats can I export visuals in?​

The API supports three output formats:

  • SVG: Scalable vector graphics (default)
  • PNG: Raster images
  • PPT: PowerPoint presentations

High Volume & Enterprise​

I expect high API volume. What should I do?​

For high-volume usage or enterprise needs, contact us to discuss custom contracts with:

  • Higher rate limits
  • Volume-based pricing
  • Dedicated support
  • Custom SLAs

Are there rate limits?​

Yes. Requests to POST /v1/visual are limited per second, per minute, per hour and per day, and the numbers depend on your plan. Rather than publish a figure that would be wrong for half of you, any answer from that endpoint that reached its limiter carries your own: read X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Window, and honour Retry-After when a 429 carries rate_limit_exceeded, which is the only one of the three 429 codes that sends it. A refusal that answers earlier — a credential, an origin, the wrong method, a body that declared itself oversized — carries none of them. The status and download endpoints are not rate limited at all.

See Errors, limits and stability for how to pace against those headers. For higher limits, contact us.

Is there an official MCP server?​

Not yet. The API is a plain REST API with three endpoints, so wrapping it as MCP tools is a small job, and several people have published their own. If you build one, tell us at api@napkin.ai — we would like to know what shape works before we commit to an official one.

Watermarks & Branding​

Will my visuals have watermarks?​

Watermarks only appear for free users without a paid subscription. Once you upgrade to any paid plan, all generated visuals will be watermark-free.

Can I use custom styles or branding?​

Yes! Napkin offers 21 built-in professional styles, and you can create custom styles to match your brand. See the Styles documentation for more details.

Troubleshooting​

What does an error look like?​

Every failed call to a visual endpoint answers JSON with the same two fields:

{
  "error": "validation_failed",
  "message": "validation failed: format is required; content is required"
}

Branch on error — those codes are stable. The message is for a human to read and may be reworded at any time. The OAuth token endpoints under /v1/oauth follow RFC 6749 instead and answer error with error_description. Every code, and which are worth retrying →

Why am I getting a "no_credits" error?​

This means your account has run out of credits. You can:

  • Upgrade your plan for more monthly credits
  • Use the top-up feature to purchase additional credits
  • Wait for your credits to refresh on your next billing cycle
  • Contact us for high-volume custom plans

You will see this as a 402 when you create the request, or as error.code on the status of a request that ran out mid-flight.

Why am I getting a "no_visuals" error?​

This error occurs when the system couldn't generate any visuals for your content. Try:

  • Simplifying your content
  • Using different parameters
  • Breaking long content into smaller chunks

What's the difference between errors and warnings?​

  • Errors indicate critical failures where no visuals were generated (e.g., no_credits, no_visuals)
  • Warnings indicate partial issues where some visuals may still be available (e.g., not_enough_visuals, some_visuals_failed_orientation_control)

How stable is the API?​

It is generally available and supported for production use. We have not committed to a formal versioning scheme yet, so here is what we do in practice: fields and error codes are added without warning, so write your client to ignore what it does not recognise; breaking changes are announced in the Changelog with the version they land in; and every response carries an X-API-Version header so you can tell which version answered. The error codes are stable — a message may be reworded, a published code will not change meaning. For support commitments or anything contractual, talk to us. What we promise about changes →

Changelog​

Where can I find the API changelog?​

You can view all API updates, new features, and changes in our Changelog.

Need Help?​

If you're facing any issues with the API or have questions not covered in this FAQ, don't hesitate to reach out. Our team is here to help!