SupportGet started

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

ToolWhat it doesSpends credits
get_profileShows which account and workspace the connection uses, so an app connected to several accounts can tell them apart.No
list_workspacesLists your workspaces with each one's plan and credits, and which one the connection is using.No
switch_workspaceMoves the connection to another of your workspaces when you ask, so new work and its credits go there.No
list_modelsLists the image and video models, with what each one costs.No
describe_modelShows every setting one model accepts.No
list_edit_operationsLists the edits it can run, such as removing a background or upscaling, with what each one costs.No
describe_edit_operationShows every setting one edit accepts.No
quote_image_generationTells you what a set of images will cost, without making them.No
quote_video_generationTells you what a video will cost, without making it.No
quote_image_editTells you what an edit will cost, without running it.No
list_projectsLists the workspace's projects, newest first.No
list_reference_setsLists 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_projectCreates a project to file new work under.No
list_project_jobsLists the jobs filed under one project, newest first.No
search_libraryFinds 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_stylesFinds 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_fileGets one file's links, size and dimensions.No
import_imageAdds an image from a public link to the workspace's library.No
upload_imageAdds an image you send to the workspace's library, to use as a reference.No
create_uploadGets a link to upload a large image or a batch CSV file to, for clients that can send files.No
complete_uploadChecks an uploaded file and makes it ready to use.No
generate_imageMakes images from a prompt and any reference images.Yes
generate_videoMakes a video from a prompt, and from images if you give them.Yes
edit_imageRuns an edit on one or more images, such as removing the background or upscaling. Some edits are free.Yes
read_resultsUsed by the results view to follow running jobs. The AI app does not see or call it.No
get_generationChecks on up to 50 generations or edits and returns their results when done, with optional previews.No
show_resultsShows up to 50 generations or edits as images and video in the chat, in apps that show results.No
quote_batchTells you what a batch of prompts will cost, and which rows can't run, without making anything.No
create_batchCreates a batch from a table of prompts, and runs it if you pass the quoted cost.Yes
get_batchShows a batch's progress and results, and can wait for it to move.No
update_batchAdds rows to a batch, runs it, or retries its failed rows.Yes
cancel_batchStops a batch's running run. Images already started finish, and the rest is refunded.No
download_filesGets 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

  1. list_models and describe_model pick a model and read its settings. The same models are listed in Models.
  2. search_library finds 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_image brings in an image from a link, and upload_image adds an image the app sends, since the create tools take files from your library, not links. For a larger image, create_upload gives the app a link to send the file to, and complete_upload finishes it.
  3. search_styles finds 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. When generate_image gets a style, Batch Banana adds its example images and a description of the look, so your prompt only needs the subject.
  4. 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.
  5. generate_image, generate_video or edit_image starts the work and charges for it. For several different images, generate_image accepts 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.
  6. get_generation checks 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 each search_library result, 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.

  1. quote_batch prices 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.
  2. create_batch makes the batch. Given the quoted price, it also starts a run of every row. update_batch adds more rows.
  3. 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.
  4. get_batch reports 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.
  5. update_batch retries the failed rows, after a new quote, and cancel_batch stops the run. Credits for rows that failed or never ran come back as one refund when the run ends.
  6. download_files returns 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_upload and complete_upload, then passes its upload ID to quote_batch, create_batch or update_batch. The file uses the same columns as the CSV import in the app, with the header line prompt,model,aspect_ratio,images,style,references,reference_sets,options. The rows import in the background, and get_batch reports 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 screenTools
Generate images and videogenerate_image, generate_video, create_batch, update_batch, cancel_batch, create_project
Edit and upscale imagesedit_image
View generation resultsget_generation, show_results, read_results, get_profile, search_library, list_projects, list_reference_sets, list_project_jobs, quote_batch, get_batch
Read your libraryget_file, download_files
Import images to your libraryimport_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:

ErrorWhat it means
UNAUTHENTICATEDThe connection is no longer signed in, usually because it was disconnected. Connect the app again.
NOT_AUTHORIZEDThe 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_FOUNDThe model, file, project or job doesn't exist, or belongs to another workspace.
INVALID_ARGUMENTA setting isn't valid for the model or edit, such as an aspect ratio it doesn't support.
INSUFFICIENT_CREDITSThe workspace doesn't have enough credits for the request.
PLAN_REQUIREDThe workspace's plan doesn't include this feature. The details name the plan that does; upgrade in Settings, under Plan.
SPEND_LIMIT_REACHEDThe 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_VERIFIEDVerify your email to continue. Open the verification link in the email from Batch Banana, then try your request again.
IDEMPOTENCY_CONFLICTA different request was sent under a request key that was already used. Try again with a new one.
PRICE_CHANGEDThe price changed after the quote. Get a new quote.
RATE_LIMITEDToo many requests in a short time. Wait a little and try again.
INTERNAL_ERRORSomething 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_image accepts 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_image takes up to 256 images per request, or 40 for an edit that costs credits, and up to 4 reference images.
  • import_image takes public https links only. Imports and uploads share one budget of 600 an hour for each connected app, in bursts of up to 100.
  • upload_image takes an image up to 5 MB. create_upload takes larger images.
  • get_generation reads 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_batch and update_batch take 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_library returns 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.