> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Tool reference > Reference for the CometAPI MCP tools: search the model catalog, inspect a model, generate text with receipts, create image tasks, and handle errors. This page describes the parameters, the results, and the errors of the CometAPI MCP tools. To connect a client and to see the charge of each tool, see [CometAPI MCP](https://apidoc.cometapi.com/developer-tools/mcp/overview.md). ## Find a model `search_models` searches the model catalog that your API key can access. The call is not billed. | Parameter | Description | | - | - | | `query` | Optional text to find in the model ID or the model owner. Enter one term, such as part of a model ID. The match ignores case. Up to 200 characters. Without `query`, the search matches all models. | | `limit` | Number of results, from 1 to 50. The default is 20. | | `offset` | Position of the first result, from 0 to 5000. The default is 0. | The result contains `data`, `total`, and `nextOffset`. To read the next page, pass the `nextOffset` value as `offset`. When `nextOffset` is `null`, the result contains the last page. `get_model_schema` returns one model. Set `model` to a model ID from the search result. The call is not billed. The `schemaStatus` field shows how you can call the model: | `schemaStatus` | Meaning | | - | - | | `verified` | A generation tool accepts the model, and `inputSchema` lists the accepted parameters and their defaults. A parameter that has a default value can be omitted, even when `inputSchema` lists it as required. | | `unavailable` | Call the model through the CometAPI API. The MCP server has no generation tool for the model. | ## Generate text `generate_text` sends one prompt to `gpt-6-astra` and returns the generated text. | Parameter | Required | Description | | - | - | - | | `model` | Yes | `gpt-6-astra` | | `prompt` | Yes | The request text, up to 4096 UTF-8 bytes | | `max_output_tokens` | No | Output token limit, from 256 to 2048. The default is 512. The limit includes reasoning tokens. | | `recovery_id` | No | A receipt from `prepare_text_generation` | The tool accepts only the parameters in this table. For the complete Responses API, see [Create a model response](https://apidoc.cometapi.com/api/text/responses.md). The result contains these fields: * `status`: `completed` or `incomplete` * `text`: the generated text * `refusal`: the refusal message when the model declines the request * `usage`: the token counts in `inputTokens`, `outputTokens`, `totalTokens`, and `reasoningTokens`. `outputTokens` includes `reasoningTokens`. * `incompleteReason`: `max_output_tokens` when the output reached the token limit, or `content_filter` when a content filter stopped the output A generation is billed when the model returns a result, including a result with the status `incomplete`. If `incompleteReason` is `max_output_tokens`, send the request again with a higher `max_output_tokens` value. The second request is billed separately. If `incompleteReason` is `content_filter`, change the prompt. ### Use a receipt for a long generation A direct `generate_text` call returns the text only in the response to that call. If the call runs for more than about 30 seconds, or the connection closes, the client receives no result. The request can still be billed, and the text cannot be read again. With a receipt, the generation can run for up to 120 seconds, and you can read the result again until the receipt expires. Use a receipt when you set `max_output_tokens` above the default value. **1. Reserve a receipt** Call `prepare_text_generation`. The result contains `recoveryId`. This call is not billed. **2. Start the generation** Call `generate_text` with your prompt, and set `recovery_id` to the `recoveryId` value. The call returns immediately with the state `running`. **3. Read the result** While `state` is `running`, call `get_text_result` with the same `recovery_id`. When `state` is `completed`, the generated text is in `result.text`. A read is not billed. A receipt starts one generation. A second `generate_text` call with the same receipt and the same parameters sends no new request and returns the state of the first request. A call with different parameters returns the `receipt_rejected` error. To send another request, reserve a new receipt. A receipt is valid for 10 minutes after you reserve it. When you start the generation, the 10 minutes start again, and `expiresAt` shows the exact time. Each API key can hold eight receipts at the same time. A receipt occupies its slot until it expires, including after its generation is completed. If `prepare_text_generation` returns the `receipt_capacity_exceeded` error, wait until a receipt expires, then reserve a receipt again. If `generate_text` returns this error for a receipt, wait until a running generation ends, then call the tool again. | `state` | Meaning | Next step | | - | - | - | | `prepared` | The receipt is reserved, and no request was sent | Call `generate_text` with the receipt | | `running` | The generation is in progress | Read the receipt again | | `completed` | The result is in `result` | Use the result | | `outcome_unknown` | The result is not known. The request can be billed. | Check your usage logs before you send the request again | | `unavailable` | The receipt expired, belongs to another API key, or is no longer stored on the server | If you started a generation with the receipt, check your usage logs before you send the request again | ## Generate an image `generate_image` submits one image task for `gpt-image-2` and returns a task ID. A task is billed when the image is generated. | Parameter | Required | Description | | - | - | - | | `model` | Yes | `gpt-image-2` | | `prompt` | Yes | The image description, up to 4096 UTF-8 bytes | | `size` | No | `1024x1024`, `1024x1536`, or `1536x1024`. The default is `1024x1024`. | | `quality` | No | `low`, `medium`, `high`, or `auto`. The default is `low`. | | `output_format` | No | The image format. Use `png` or `jpeg`. The default is `jpeg`. | Each task creates one image. For other image options, see [Create an image](https://apidoc.cometapi.com/api/image/openai/images.md). **1. Submit the task** Call `generate_image`. The result contains `taskId` and a `status` of `pending`, `success`, or `failure`. **2. Read the task** While `status` is `pending`, call `get_task` with `task_id` set to the `taskId` value. A task read is not billed. Do not call `generate_image` again, because each call submits a new task. **3. Save the image** When `status` is `success`, save the image with the command in the next section. The `get_task` result also contains the image as base64 text, in the `b64_json` field of the first item in `data`. If `status` is `failure`, the task did not produce an image. The `failReason` field contains a general message. To read the cause, retrieve the task from the CometAPI API and read `data.fail_reason`. See [Retrieve an image generation task](https://apidoc.cometapi.com/api/image/openai/image-generation-task.md). If the cause is a request error, correct the parameters and submit another task. For any other cause, contact [CometAPI support](https://www.cometapi.com/support/) with the task ID. ### Save the image as a file The base64 text of an image is large and can exceed the tool output limit of the client. To save the image without passing the base64 text through the conversation, retrieve the task from the CometAPI API with the same task ID and API key. In the API response, the task state is in `data.status`, and the image is in the `b64_json` field of the first item in `data.data`. The following command saves a JPEG image. Replace `` with the task ID: ```bash theme={null} set -o pipefail curl -fsS "https://api.cometapi.com/v1/images/generations/" \ -H "Authorization: Bearer $COMETAPI_KEY" \ | jq -er 'select(.data.status == "success") | .data.data[0].b64_json' \ | base64 --decode > image.jpeg ``` The command requires `curl` and `jq`. If the task is not yet `success`, or the API key is not valid, the command ends with a nonzero exit status, and the file is empty. For a PNG image, change the file name to `image.png`. If the image does not fit in a tool result, `get_task` returns the `image_output_too_large` error. The task is still available from the CometAPI API. ## Errors When a tool reports an error, the result contains an `error` object with these fields: | Field | Description | | - | - | | `type` | The error code, such as `model_not_found` | | `message` | A description of the problem and the next step | | `upstreamStatus` | The HTTP status code from the CometAPI API, or `null` | | `submission` | For generation and task tools, the state of the request | | `retryable` | For generation and task tools, `false`. Check the first request before you send the request again. | | `correlationId` | The identifier of the request. Include it when you contact support. | If the arguments do not match the parameters of a tool, the call returns a validation message instead of an `error` object. The request is not sent, and it is not billed. The `submission` field shows whether a request can be billed: | `submission` | Meaning | Next step | | - | - | - | | `not_submitted` | This call sent no request, and this call is not billed | Follow the instructions in `message`. For `receipt_rejected`, if an earlier call with the same receipt started a generation, check your usage logs before you send the request again. | | `unknown` | The request was sent, and the tool has no result. The request can be billed. | Check your usage logs before you send the request again | | `accepted` | CometAPI answered the image request, but the tool cannot return the task. The task is billed when the image is generated. | The error contains no task ID. Check your usage logs before you submit the image again. | | `observed` | The error came from a task read. A task read is not billed. | Do not submit another task. For `image_task_not_found`, check the task ID and the API key. For `image_output_too_large`, retrieve the task from the CometAPI API. For any other error, read the same task ID again. | Successful results also contain `submission`: `completed` in a text result, `accepted` from `generate_image`, and `observed` from `get_task`. For the checks to make before you send a billed request again, see the Billing section of [CometAPI MCP](https://apidoc.cometapi.com/developer-tools/mcp/overview.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.