MCP tools
See which MCP tools generate and edit images, run batches, search your library, quote costs and use workspace credits.
Last verified
Use this reference to check what a connected AI app can do, which tools spend credits, and what permissions they need. Your app calls the tools for you.
Tools
| Tool | What it does | Spends credits |
|---|---|---|
get_profile | Shows which account and workspace the connection uses, so an app connected to several accounts can tell them apart. | No |
list_workspaces | Lists your workspaces with each one's plan and credits, and which one the connection is using. | No |
switch_workspace | Moves the connection to another of your workspaces when you ask, so new work and its credits go there. | No |
list_models | Lists the image and video models, with what each one costs. | No |
describe_model | Shows every setting one model accepts. | No |
list_edit_operations | Lists the edits it can run, such as removing a background or upscaling, with what each one costs. | No |
describe_edit_operation | Shows every setting one edit accepts. | No |
quote_image_generation | Tells you what a set of images will cost, without making them. | No |
quote_video_generation | Tells you what a video will cost, without making it. | No |
quote_image_edit | Tells you what an edit will cost, without running it. | No |
list_projects | Lists the workspace's projects, newest first. | No |
list_reference_sets | Lists your saved reference sets, such as a project's style or a character, with their images and which ones go on every image. | No |
create_project | Creates a project to file new work under. | No |
list_project_jobs | Lists the jobs filed under one project, newest first. | No |
search_library | Finds work already in the workspace by prompt, kind, model, edit operation, project or date. One result per job, with its cost and reference images. | No |
search_styles | Finds looks in the Batch Banana style library by description, such as watercolor or claymation, lists the library by family, or reads chosen styles in full, to pass to generate_image. | No |
get_file | Gets one file's links, size and dimensions. | No |
import_image | Adds an image from a public link to the workspace's library. | No |
upload_image | Adds an image you send to the workspace's library, to use as a reference. | No |
create_upload | Gets a link to upload a large image or a batch CSV file to, for clients that can send files. | No |
complete_upload | Checks an uploaded file and makes it ready to use. | No |
generate_image | Makes images from a prompt and any reference images. | Yes |
generate_video | Makes a video from a prompt, and from images if you give them. | Yes |
edit_image | Runs an edit on one or more images, such as removing the background or upscaling. Some edits are free. | Yes |
read_results | Used by the results view to follow running jobs. The AI app does not see or call it. | No |
get_generation | Checks on up to 50 generations or edits and returns their results when done, with optional previews. | No |
show_results | Shows up to 50 generations or edits as images and video in the chat, in apps that show results. | No |
quote_batch | Tells you what a batch of prompts will cost, and which rows can't run, without making anything. | No |
create_batch | Creates a batch from a table of prompts, and runs it if you pass the quoted cost. | Yes |
get_batch | Shows a batch's progress and results, and can wait for it to move. | No |
update_batch | Adds rows to a batch, runs it, or retries its failed rows. | Yes |
cancel_batch | Stops a batch's running run. Images already started finish, and the rest is refunded. | No |
download_files | Gets links that save an image, a result's images as a ZIP, or a batch's images as ZIP files. | No |
No tool deletes anything. The tools marked Yes spend the workspace's credits. edit_image spends them only for edits that cost credits, and create_batch and update_batch spend them only when they start a run.
How a request runs
list_modelsanddescribe_modelpick a model and read its settings. The same models are listed in Models.search_libraryfinds earlier work to use as references, by prompt, kind, model, edit operation, project or date. Each result is one job with its files, cost and reference images.import_imagebrings in an image from a link, andupload_imageadds an image the app sends, since the create tools take files from your library, not links. For a larger image,create_uploadgives the app a link to send the file to, andcomplete_uploadfinishes it.search_stylesfinds styles in the Batch Banana style library from a name or description, such as watercolor or claymation. Each result includes a short description and says whether it matched the name or the look. With no search text, it lists every style by family. It can also return full details for selected styles. If your account cannot search by description, it still finds styles you name; otherwise, it returns the full list. Whengenerate_imagegets a style, Batch Banana adds its example images and a description of the look, so your prompt only needs the subject.- A quote tool returns the price without charging. The create tools also report what they charged, so a quote is only needed to check a price first.
generate_image,generate_videooredit_imagestarts the work and charges for it. For several different images,generate_imageaccepts a list of prompts in one request. Supported apps show the images from that request together in a results view. In ChatGPT, the view also includes images from other requests made in the same reply.get_generationchecks up to 50 jobs at a time until they finish and returns a link to each file. With previews turned on, it also returns up to 8 small images the app can look at. Each job, and eachsearch_libraryresult, also links to your Library at the day it was made, which the results view shows as Open in Batch Banana.
show_results opens selected generations and edits in the results view, including work made earlier in a conversation. The view uses read_results to check progress until the work finishes. This tool is only available to the view. get_profile tells the app which account and workspace a connection uses, so an app connected to several accounts can tell them apart.
Every tool works in the connection's current workspace. list_workspaces shows your workspaces with each one's plan and credits, and switch_workspace moves the connection to another of them. The app switches only when you ask, never on its own, because new work and its credits then go to the other workspace.
create_project makes a project to file new work under, optionally with its icon and color, and list_project_jobs lists the work in one.
list_reference_sets lists your references: a project's own, then the workspace's, each with its type, its note and its images. generate_image, generate_video and the batch tools take referenceSets, a list of references by ID or exact name, or as {"set": ..., "images": [...]} to send only some of a reference's images for that request. Your own images go first; the references and any style then take turns until the model is full, and each job's references says how many images each source sent. Image requests and new batches filed under a project also get the references marked Auto-attach there, unless the app passes autoAttach: false, which it does only when you ask for an image without them. Video uses only the references the request names. Each job lists the references that sent images in referenceSetIds. The quote tools take the same fields and projectId, so a quote prices the reference images the request will send.
A request key prevents duplicate charges: retrying with the same key returns the original job. If the app includes a quoted price and that price has changed, the server rejects the request before charging.
How a batch runs
A batch is a table of prompts that run together, the same Batch you use in the app. Each row has a prompt and can set its own model, style, aspect ratio, image count and reference images, given as library file IDs or https image links. The batch's defaults.referenceSets go on every row, after the project's Auto-attach references, and a row's referenceSets add to them.
quote_batchprices the rows without charging or saving anything and lists each row that can't run, with the field at fault and how to fix it. Image links are counted in the price and imported only when the rows are saved.create_batchmakes the batch. Given the quoted price, it also starts a run of every row.update_batchadds more rows.- A run starts in a preparing step, prices every row again and charges the whole run once. If the price no longer matches the quote, nothing is charged and the run stops with
PRICE_CHANGED. get_batchreports progress in one line. It can wait up to 45 seconds for progress, return a page of results with links, and return up to 8 small image previews for the app to look at.update_batchretries the failed rows, after a new quote, andcancel_batchstops the run. Credits for rows that failed or never ran come back as one refund when the run ends.download_filesreturns links to ZIP files of the images, up to 1,000 rows each. The links work for an hour.
download_files also returns a link that saves one file, or one ZIP file with every output of up to 50 jobs, so any result can be downloaded. The app gives you the links to open in your browser.
Rows reach a batch in one of two ways, with the same checks either way:
- Sent directly, up to 500 rows per call. Apps without a shell, such as ChatGPT and Claude.ai, use this.
- As a CSV file of up to 20,000 rows and 25 MB, for apps that can send a file, such as Claude Code, Codex and Cursor. The app uploads the file with
create_uploadandcomplete_upload, then passes its upload ID toquote_batch,create_batchorupdate_batch. The file uses the same columns as the CSV import in the app, with the header lineprompt,model,aspect_ratio,images,style,references,reference_sets,options. The rows import in the background, andget_batchreports the import's progress, or every problem by line with how to fix it. A file with a problem saves nothing unless the app asks to skip the rows with problems.
If the model is busy, a batch row waits and tries again on its own, at no extra cost. Batches need the Max plan; on other plans the batch tools return PLAN_REQUIRED, though existing batches can still be read and downloaded.
Permissions
The consent screen lists five permissions. Each one covers these tools:
| On the consent screen | Tools |
|---|---|
| Generate images and video | generate_image, generate_video, create_batch, update_batch, cancel_batch, create_project |
| Edit and upscale images | edit_image |
| View generation results | get_generation, show_results, read_results, get_profile, search_library, list_projects, list_reference_sets, list_project_jobs, quote_batch, get_batch |
| Read your library | get_file, download_files |
| Import images to your library | import_image, upload_image, create_upload, complete_upload |
Saving a batch row with an image link also needs Import images to your library, because the image is imported when the row is saved. Getting a price does not.
Tools that list models, describe edit operations, search styles or quote single requests return public catalog and pricing information. They do not need the workspace permissions listed above.
Errors
When a request fails, the app gets one of these codes:
| Error | What it means |
|---|---|
UNAUTHENTICATED | The connection is no longer signed in, usually because it was disconnected. Connect the app again. |
NOT_AUTHORIZED | The connection isn't allowed to make this request. When you are no longer a member of the connection's current workspace, the details list your workspaces to switch it to. |
NOT_FOUND | The model, file, project or job doesn't exist, or belongs to another workspace. |
INVALID_ARGUMENT | A setting isn't valid for the model or edit, such as an aspect ratio it doesn't support. |
INSUFFICIENT_CREDITS | The workspace doesn't have enough credits for the request. |
PLAN_REQUIRED | The workspace's plan doesn't include this feature. The details name the plan that does; upgrade in Settings, under Plan. |
SPEND_LIMIT_REACHED | The API key or connection reached its daily credit limit in this workspace. It resets at midnight UTC, or the workspace owner can raise it in Settings, on that key or connection. |
EMAIL_NOT_VERIFIED | Verify your email to continue. Open the verification link in the email from Batch Banana, then try your request again. |
IDEMPOTENCY_CONFLICT | A different request was sent under a request key that was already used. Try again with a new one. |
PRICE_CHANGED | The price changed after the quote. Get a new quote. |
RATE_LIMITED | Too many requests in a short time. Wait a little and try again. |
INTERNAL_ERROR | Something went wrong on our side. Try again, and contact support if it keeps happening. |
SPEND_LIMIT_REACHED means the request would take the connection past its daily credit limit. See Daily credit limit.
When the workspace's plan doesn't include what you asked for, such as a batch, the app tells you which plan does and links to plans. If another of your workspaces has that plan, it says so, and you can ask it to switch or pick another workspace from the ⋯ menu next to the app in Settings > Connected apps. If you are no longer a member of the workspace the connection is using, the app lists your workspaces so you can pick one the same way.
A job can also fail after it starts, for example when the model's provider refuses the prompt or an image. The app is told why, and the job's credits go back to the workspace.
Limits
generate_imageaccepts up to 16 prompts per request, up to 8 images per prompt, and up to 48 images in total. Without an image count, a single prompt makes 4 images, including a list containing just one prompt. A list of several prompts makes 1 image per prompt.edit_imagetakes up to 256 images per request, or 40 for an edit that costs credits, and up to 4 reference images.import_imagetakes publichttpslinks only. Imports and uploads share one budget of 600 an hour for each connected app, in bursts of up to 100.upload_imagetakes an image up to 5 MB.create_uploadtakes larger images.get_generationreads up to 50 jobs per call.- A request names up to 20 references. When they hold more images than the model takes, each sends its first images in turn until the model is full, and a reference with no room left is left off.
- A batch holds up to 20,000 rows.
quote_batch,create_batchandupdate_batchtake up to 500 rows per call, with up to 50 different image links per call, or a CSV file of up to 20,000 rows and 25 MB with up to 100 different image links. search_libraryreturns about 20 jobs per page, up to 100 on request. Edits and imports have no prompt, so a prompt search does not find them; the app filters by kind or edit operation instead.
Daily credit limit
A connected app has no daily credit limit until a workspace's owner sets one for it, from Daily limit in the app's menu under Settings > MCP. Each workspace has its own limit for the app. Every charge the app makes in the workspace counts toward its limit there, so moving the app to another workspace starts it on that workspace's limit. The full cost of a batch run counts when the run is charged. Refunds reduce the amount counted. The day resets at midnight UTC. A request that would go over the limit is refused with SPEND_LIMIT_REACHED, and nothing is charged.
To change the limit or turn it off, the workspace owner opens Settings > MCP and chooses Daily limit from the ⋯ menu next to the app under Connected apps. Once the app spends credits that day, its row shows how much. API keys have the same setting under API keys, with no limit until an owner sets one. Spending in the Batch Banana app itself is never limited this way.
API access
Batch Banana also has an API, which our team turns on per workspace. To ask for it, open Settings > MCP and choose Contact us under API keys.