How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.
Every API request is paid in Gems from your account. Membership plans and their unlimited models do not apply to the API.
The API and the MCP server need a successful payment on your
account first: buy any Gem pack or plan. Until
then every call answers 402 payment_required. The signup bonus works in the
Mage app only. Keys made before the payment start working as soon as it goes
through.
The price depends on the model and its settings: resolution, duration, and on some models the number of references. Each model’s page shows the price of its default settings. Before you submit, GET /v1/account shows the balance; after you submit, billing.gems_charged on the request shows the exact charge. A request the balance cannot cover is refused with 402 insufficient_gems and gems_required, and nothing is charged.
If auto top-up is on for your account, an API request that needs more Gems than the balance holds triggers it exactly as a generation in the app would, including the charge to your card. Manage it in API → Billing, where you can also see your Gem balances and transactions. Billing shows a warning when auto top-up is disabled; leave it off if you want API spend bounded by the balance. See how Gems work.
Results and inputs live in a 30-day temporary area. A result’s expires_at and an upload ticket’s url_expires_at say when each URL stops working. A completed request stays completed after its media expires; only the download stops. Copy anything you want to keep to your own storage.
Last modified on October 29, 2026
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Mage","description":"Documentation for Mage, the AI image, video, and audio generation platform: models, apps, membership plans, Gems, and content rules.","colors":{"primary":"#fd7e14","light":"#fd7e14","dark":"#fd7e14"},"logo":{"light":"https://mintcdn.com/mage-space/YzEDodIOcFhjY5Nm/logo/light.png?fit=max\u0026auto=format\u0026n=YzEDodIOcFhjY5Nm\u0026q=85\u0026s=64222af9a7e55b8fd0c6f477679de40d","dark":"https://mintcdn.com/mage-space/YzEDodIOcFhjY5Nm/logo/dark.png?fit=max\u0026auto=format\u0026n=YzEDodIOcFhjY5Nm\u0026q=85\u0026s=6ac3e3aa905a6f399b43761d4f315a98","href":"https://www.mage.space"},"favicon":"https://mintcdn.com/mage-space/js7ICkpl6EjyCpqj/favicon.png?fit=max\u0026auto=format\u0026n=js7ICkpl6EjyCpqj\u0026q=85\u0026s=ac1b3dcc728d70f5f6e1f83e64131497","api":{"playground":{"display":"interactive"},"examples":{"languages":["curl","typescript","python","javascript"]}},"appearance":{"default":"dark"},"navbar":{"links":[{"href":"https://github.com/mage-space","label":"GitHub"},{"href":"https://www.mage.space/blog","label":"Blog"},{"href":"https://discord.gg/GT9bPgxyFP","label":"Community"}],"primary":{"type":"button","label":"Open Mage","href":"https://www.mage.space"}},"footer":{"socials":{"website":"https://www.mage.space","x":"https://x.com/MageSpace_","instagram":"https://www.instagram.com/magespace_","discord":"https://discord.gg/GT9bPgxyFP"}},"search":{"prompt":"Search Mage docs"},"seo":{"metatags":{"og:site_name":"Mage Docs","canonical":"https://docs.mage.space","msvalidate.01":"5EDBC0AF9865EE5A2B8FF37EA278E2FF"},"organization":{"name":"Mage","legalName":"Ollano, Inc.","url":"https://www.mage.space","sameAs":["https://x.com/MageSpace_","https://www.youtube.com/@MageSpace","https://www.instagram.com/magespace_","https://www.tiktok.com/@magespace_","https://www.linkedin.com/company/magespace","https://github.com/mage-space","https://discord.gg/GT9bPgxyFP"]},"indexing":"navigable"},"fonts":{"family":"Inter"},"integrations":{"posthog":{"apiKey":"phc_lBVvvz084lS4XFbPqGf38TGEa6HnGhmgVHcf4f0NNuX","apiHost":"https://ph.mage.space","sessionRecording":false}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","cursor","vscode"],"display":"header"},"metadata":{"timestamp":true},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"mage-space","hasAudioNarration":false,"actualSubdomain":"mage-space","customDomains":["docs.mage.space"],"gitSource":{"type":"github","owner":"ollanoinc","repo":"mage","deployBranch":"master","contentDirectory":"apps/docs","isPrivate":true,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6ae6177a3aae848cfc96f715","collectionId":"7cce8119-0f0e-476e-8d96-988ff894b41b","liveDeploymentHistoryId":"6ae6177a3aae848cfc96f715","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6ae6177a3aae848cfc96f715","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"default","tag":"API","count":59},{"language":"default","tag":"Models","count":39},{"language":"default","tag":"Guides","count":27},{"language":"default","tag":"Apps","count":21},{"language":"default","tag":"Image models","count":16},{"language":"default","tag":"Video models","count":13},{"language":"default","tag":"Open-weights models","count":13},{"language":"default","tag":"Endpoints","count":12},{"language":"default","tag":"Features","count":12},{"language":"default","tag":"Mage models","count":11}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api/billing","slug":"/api/billing","pageMetadata":{"title":"Billing and retention","sidebarTitle":"Billing and retention","description":"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.","href":"/api/billing"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{Heading,Table,Warning}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Every API request is paid in Gems from your account. Membership plans and their unlimited models do not apply to the API.`}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`The API and the `,_jsx(_components.a,{href:`/api/mcp`,children:`MCP server`}),` need a successful payment on your\naccount first: buy any `,_jsx(_components.a,{href:`https://www.mage.space/gems`,children:`Gem pack or plan`}),`. Until\nthen every call answers `,_jsx(_components.code,{children:`402 payment_required`}),`. The signup bonus works in the\nMage app only. Keys made before the payment start working as soon as it goes\nthrough.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`prices`,children:`Prices`}),`\n`,_jsxs(_components.p,{children:[`The price depends on the model and its settings: resolution, duration, and on some models the number of references. Each model’s page shows the price of its default settings. Before you submit, `,_jsx(_components.code,{children:`GET /v1/account`}),` shows the balance; after you submit, `,_jsx(_components.code,{children:`billing.gems_charged`}),` on the request shows the exact charge. A request the balance cannot cover is refused with `,_jsx(_components.code,{children:`402 insufficient_gems`}),` and `,_jsx(_components.code,{children:`gems_required`}),`, and nothing is charged.`]}),`\n`,_jsx(Heading,{level:`2`,id:`when-gems-move`,children:`When Gems move`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Event`}),_jsx(_components.th,{children:`Gems`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`The request is accepted`}),_jsxs(_components.td,{children:[`Charged. `,_jsx(_components.code,{children:`billing.gems_charged`}),` is the price.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`The generation fails`}),_jsxs(_components.td,{children:[`Refunded. The status read shows `,_jsx(_components.code,{children:`gems_refunded`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`The model’s provider blocks the content`}),_jsxs(_components.td,{children:[`Refunded. The request reports `,_jsx(_components.code,{children:`failed`}),` with `,_jsx(_components.code,{children:`content_blocked`}),` and a `,_jsx(_components.a,{href:`/api/errors#provider-blocks`,children:_jsx(_components.code,{children:`reason`})}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Mage’s content policy forbids the output`}),_jsxs(_components.td,{children:[`Kept, as in the app. The request reports `,_jsx(_components.code,{children:`failed`}),` with `,_jsx(_components.code,{children:`content_blocked`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`You cancel the request`}),_jsx(_components.td,{children:`Kept, as in the app.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`The request is refused before it runs`}),_jsx(_components.td,{children:`Nothing is charged.`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`auto-top-up`,children:`Auto top-up`}),`\n`,_jsxs(_components.p,{children:[`If auto top-up is on for your account, an API request that needs more Gems than the balance holds triggers it exactly as a generation in the app would, including the charge to your card. Manage it in `,_jsx(_components.a,{href:`https://www.mage.space/api?tab=billing`,children:`API → Billing`}),`, where you can also see your Gem balances and transactions. Billing shows a warning when auto top-up is disabled; leave it off if you want API spend bounded by the balance. See `,_jsx(_components.a,{href:`/plans/how-gems-work`,children:`how Gems work`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`retention`,children:`Retention`}),`\n`,_jsxs(_components.p,{children:[`Results and inputs live in a 30-day temporary area. A result’s `,_jsx(_components.code,{children:`expires_at`}),` and an upload ticket’s `,_jsx(_components.code,{children:`url_expires_at`}),` say when each URL stops working. A completed request stays `,_jsx(_components.code,{children:`completed`}),` after its media expires; only the download stops. Copy anything you want to keep to your own storage.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Billing and retention","sidebarTitle":"Billing and retention","description":"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.","href":"/api/billing"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Prices","slug":"prices","depth":2,"children":[]},{"title":"When Gems move","slug":"when-gems-move","depth":2,"children":[]},{"title":"Auto top-up","slug":"auto-top-up","depth":2,"children":[]},{"title":"Retention","slug":"retention","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"mage-space","siteName":"Mage","title":"Billing and retention - Mage","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-29T04:00:13.654Z","gitLastModified":"2026-10-29T03:59:59.000Z","originalFileLocation":"api/billing.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Mage\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Billing and retention - Mage\">\u003cmeta data-mint-head property=\"og:description\" content=\"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Mage Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.mage.space/api/billing\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://mage-space.mintlify.app/_mintlify/api/og/v2?division=Concepts\u0026amp;title=Billing+and+retention\u0026amp;description=How+the+Mage+API+charges+Gems%3A+the+price+of+a+request%2C+when+it+is+charged+and+refunded%2C+cancellations%2C+auto+top-up%2C+and+how+long+results+and+inputs+are+kept.\u0026amp;theme=15e3959de07cfae439e998da\u0026amp;signature=d94a0603f6a5b819a8699c88b4cdc7bf5c2a08cd670b66259639844f2855a62f\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Billing and retention - Mage\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://mage-space.mintlify.app/_mintlify/api/og/v2?division=Concepts\u0026amp;title=Billing+and+retention\u0026amp;description=How+the+Mage+API+charges+Gems%3A+the+price+of+a+request%2C+when+it+is+charged+and+refunded%2C+cancellations%2C+auto+top-up%2C+and+how+long+results+and+inputs+are+kept.\u0026amp;theme=15e3959de07cfae439e998da\u0026amp;signature=d94a0603f6a5b819a8699c88b4cdc7bf5c2a08cd670b66259639844f2855a62f\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/mage-space/RwBJFP0egq-BZOBp/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Mage\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#fd7e14\">\u003cmeta data-mint-head name=\"msvalidate.01\" content=\"5EDBC0AF9865EE5A2B8FF37EA278E2FF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.mage.space/api/billing\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/billing.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://www.mage.space/#organization\",\"name\":\"Mage\",\"legalName\":\"Ollano, Inc.\",\"url\":\"https://www.mage.space\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/mage-space/YzEDodIOcFhjY5Nm/logo/light.png?fit=max\u0026auto=format\u0026n=YzEDodIOcFhjY5Nm\u0026q=85\u0026s=64222af9a7e55b8fd0c6f477679de40d\"},\"sameAs\":[\"https://x.com/MageSpace_\",\"https://www.youtube.com/@MageSpace\",\"https://www.instagram.com/magespace_\",\"https://www.tiktok.com/@magespace_\",\"https://www.linkedin.com/company/magespace\",\"https://github.com/mage-space\",\"https://discord.gg/GT9bPgxyFP\"]},{\"@type\":\"WebSite\",\"@id\":\"https://docs.mage.space#website\",\"name\":\"Mage\",\"url\":\"https://docs.mage.space\",\"publisher\":{\"@id\":\"https://www.mage.space/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.mage.space/api/billing#webpage\",\"url\":\"https://docs.mage.space/api/billing\",\"name\":\"Billing and retention\",\"description\":\"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.\",\"dateModified\":\"2026-10-29T03:59:59.000Z\",\"isPartOf\":{\"@id\":\"https://docs.mage.space#website\"},\"breadcrumb\":{\"@id\":\"https://docs.mage.space/api/billing#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.mage.space/api/billing#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Concepts\",\"item\":\"https://docs.mage.space/api/requests\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Billing and retention\",\"item\":\"https://docs.mage.space/api/billing\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.mage.space/api/billing#article\",\"headline\":\"Billing and retention\",\"name\":\"Billing and retention\",\"description\":\"How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.\",\"url\":\"https://docs.mage.space/api/billing\",\"mainEntityOfPage\":{\"@id\":\"https://docs.mage.space/api/billing#webpage\"},\"dateModified\":\"2026-10-29T03:59:59.000Z\",\"publisher\":{\"@id\":\"https://www.mage.space/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.mage.space#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Mage\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Mage","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"Models","pages":[{"title":"Models","href":"/models/overview"}]},{"tab":"Apps","pages":[{"title":"Apps","href":"/apps/overview"}]},{"tab":"API","groups":[{"group":"Get started","pages":[{"title":"Mage API","sidebarTitle":"Overview","href":"/api/overview"},{"title":"Quickstart","sidebarTitle":"Quickstart","href":"/api/quickstart"},{"title":"Authentication","sidebarTitle":"Authentication","href":"/api/authentication"},{"title":"Use Mage from Claude, ChatGPT, Grok, and Cursor","sidebarTitle":"MCP server","href":"/api/mcp"}]},{"group":"SDKs and integrations","pages":[{"title":"TypeScript SDK","sidebarTitle":"TypeScript","href":"/api/sdks/typescript"},{"title":"Python SDK","sidebarTitle":"Python","href":"/api/sdks/python"},{"title":"Mage for ComfyUI","sidebarTitle":"ComfyUI","href":"/api/integrations/comfyui"},{"title":"Mage skills for Claude, Codex, and Cursor","sidebarTitle":"Agent skills","href":"/api/integrations/skills"}]},{"group":"Concepts","pages":[{"title":"Requests and lifecycle","sidebarTitle":"Requests and lifecycle","href":"/api/requests"},{"title":"Inputs and uploads","sidebarTitle":"Inputs and uploads","href":"/api/inputs"},{"title":"Errors and retries","sidebarTitle":"Errors and retries","href":"/api/errors"},{"title":"Rate limits and concurrency","sidebarTitle":"Rate limits","description":"The limits on Mage API use: generations in flight per account, active keys, request body and input sizes, and how to design a client around them.","href":"/api/limits"},{"title":"Billing and retention","sidebarTitle":"Billing and retention","href":"/api/billing"},{"title":"Versioning and changes","sidebarTitle":"Versioning","description":"How the Mage API changes over time: what ships within v1, what waits for v2, how deprecations are announced, and what a client must tolerate.","href":"/api/versioning"}]},{"group":"Endpoints","pages":[{"title":"Generate","sidebarTitle":"Generate","openapi":"api/openapi.json POST /v1/{architecture}/generate","href":"/api/endpoints/generate"},{"title":"List architectures","sidebarTitle":"List architectures","openapi":"api/openapi.json GET /v1/architectures","href":"/api/endpoints/list-architectures"},{"title":"Get request status","sidebarTitle":"Get request status","openapi":"api/openapi.json GET /v1/requests/{request_id}/status","href":"/api/endpoints/get-request-status"},{"title":"Cancel request","sidebarTitle":"Cancel request","openapi":"api/openapi.json POST /v1/requests/{request_id}/cancel","href":"/api/endpoints/cancel-request"},{"title":"Get account","sidebarTitle":"Get account","openapi":"api/openapi.json GET /v1/account","href":"/api/endpoints/get-account"},{"title":"Create upload","sidebarTitle":"Create upload","openapi":"api/openapi.json POST /v1/uploads","href":"/api/endpoints/create-upload"},{"title":"List characters","sidebarTitle":"List characters","openapi":"api/openapi.json GET /v1/characters","href":"/api/endpoints/list-characters"},{"title":"Create character","sidebarTitle":"Create character","openapi":"api/openapi.json POST /v1/characters","href":"/api/endpoints/create-character"},{"title":"Delete character","sidebarTitle":"Delete character","openapi":"api/openapi.json DELETE /v1/characters/{character_id}","href":"/api/endpoints/delete-character"},{"title":"List references","sidebarTitle":"List references","openapi":"api/openapi.json GET /v1/references","href":"/api/endpoints/list-references"},{"title":"Create reference","sidebarTitle":"Create reference","openapi":"api/openapi.json POST /v1/references","href":"/api/endpoints/create-reference"},{"title":"Delete reference","sidebarTitle":"Delete reference","openapi":"api/openapi.json DELETE /v1/references/{reference_id}","href":"/api/endpoints/delete-reference"}]},{"group":"Models","pages":[{"title":"Models in the API","sidebarTitle":"Overview","href":"/api/models/overview"}]},{"group":"Image models","pages":[{"title":"Anima","sidebarTitle":"Anima","openapi":"api/openapi.json POST /v1/anima/generate","href":"/api/models/anima"},{"title":"Chroma","sidebarTitle":"Chroma","openapi":"api/openapi.json POST /v1/chroma/generate","href":"/api/models/chroma"},{"title":"Flux 2","sidebarTitle":"Flux 2","openapi":"api/openapi.json POST /v1/flux2/generate","href":"/api/models/flux2"},{"title":"GPT Image 2","sidebarTitle":"GPT Image 2","openapi":"api/openapi.json POST /v1/gpt_image_2/generate","href":"/api/models/gpt_image_2"},{"title":"Grok Image","sidebarTitle":"Grok Image","openapi":"api/openapi.json POST /v1/grok_image/generate","href":"/api/models/grok_image"},{"title":"Guava","sidebarTitle":"Guava","openapi":"api/openapi.json POST /v1/guava/generate","href":"/api/models/guava"},{"title":"HiDream","sidebarTitle":"HiDream","openapi":"api/openapi.json POST /v1/hidream/generate","href":"/api/models/hidream"},{"title":"Krea 2","sidebarTitle":"Krea 2","openapi":"api/openapi.json POST /v1/krea_2/generate","href":"/api/models/krea_2"},{"title":"Mango","sidebarTitle":"Mango","openapi":"api/openapi.json POST /v1/mango/generate","href":"/api/models/mango"},{"title":"MOSS-Image","sidebarTitle":"MOSS-Image","openapi":"api/openapi.json POST /v1/moss_image/generate","href":"/api/models/moss_image"},{"title":"Nano Banana 2","sidebarTitle":"Nano Banana 2","openapi":"api/openapi.json POST /v1/nano_banana_v2/generate","href":"/api/models/nano_banana_v2"},{"title":"SDXL Plus","sidebarTitle":"SDXL Plus","openapi":"api/openapi.json POST /v1/sdxl_plus/generate","href":"/api/models/sdxl_plus"},{"title":"Stable Diffusion v1.5","sidebarTitle":"Stable Diffusion v1.5","openapi":"api/openapi.json POST /v1/stable_diffusion_v15/generate","href":"/api/models/stable_diffusion_v15"},{"title":"Stable Diffusion v3.5 Large","sidebarTitle":"Stable Diffusion v3.5 Large","openapi":"api/openapi.json POST /v1/stable_diffusion_v35_large/generate","href":"/api/models/stable_diffusion_v35_large"},{"title":"Stable Diffusion XL","sidebarTitle":"Stable Diffusion XL","openapi":"api/openapi.json POST /v1/stable_diffusion_xl/generate","href":"/api/models/stable_diffusion_xl"},{"title":"Z-Image","sidebarTitle":"Z-Image","openapi":"api/openapi.json POST /v1/z_image/generate","href":"/api/models/z_image"}]},{"group":"Video models","pages":[{"title":"Berry","sidebarTitle":"Berry","openapi":"api/openapi.json POST /v1/berry/generate","href":"/api/models/berry"},{"title":"Blueberry","sidebarTitle":"Blueberry","openapi":"api/openapi.json POST /v1/blueberry/generate","href":"/api/models/blueberry"},{"title":"Cherry","sidebarTitle":"Cherry","openapi":"api/openapi.json POST /v1/cherry/generate","href":"/api/models/cherry"},{"title":"Grok Video","sidebarTitle":"Grok Video","openapi":"api/openapi.json POST /v1/grok_video/generate","href":"/api/models/grok_video"},{"title":"Kiwi","sidebarTitle":"Kiwi","openapi":"api/openapi.json POST /v1/kiwi/generate","href":"/api/models/kiwi"},{"title":"Lemon","sidebarTitle":"Lemon","openapi":"api/openapi.json POST /v1/lemon/generate","href":"/api/models/lemon"},{"title":"LTX Video","sidebarTitle":"LTX Video","openapi":"api/openapi.json POST /v1/ltx_video/generate","href":"/api/models/ltx_video"},{"title":"Magejutsu","sidebarTitle":"Magejutsu","openapi":"api/openapi.json POST /v1/magejutsu/generate","href":"/api/models/magejutsu"},{"title":"Melon","sidebarTitle":"Melon","openapi":"api/openapi.json POST /v1/melon/generate","href":"/api/models/melon"},{"title":"MiniMax-H3","sidebarTitle":"MiniMax-H3","openapi":"api/openapi.json POST /v1/minimax_h3/generate","href":"/api/models/minimax_h3"},{"title":"Plum","sidebarTitle":"Plum","openapi":"api/openapi.json POST /v1/plum/generate","href":"/api/models/plum"},{"title":"Raspberry","sidebarTitle":"Raspberry","openapi":"api/openapi.json POST /v1/raspberry/generate","href":"/api/models/raspberry"},{"title":"Wan Video v2.2","sidebarTitle":"Wan Video v2.2","openapi":"api/openapi.json POST /v1/wan_22/generate","href":"/api/models/wan_22"}]},{"group":"Audio models","pages":[{"title":"Eleven Music","sidebarTitle":"Eleven Music","openapi":"api/openapi.json POST /v1/eleven_music/generate","href":"/api/models/eleven_music"},{"title":"Eleven Speech","sidebarTitle":"Eleven Speech","openapi":"api/openapi.json POST /v1/eleven_speech/generate","href":"/api/models/eleven_speech"},{"title":"Seed Audio","sidebarTitle":"Seed Audio","openapi":"api/openapi.json POST /v1/seed_audio/generate","href":"/api/models/seed_audio"}]}]}]},"basePath":"","title":"Billing and retention - Mage","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":[],"chunks":[]}
