Tool reference

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.

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. 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.

Reserve a receipt

Call prepare_text_generation. The result contains recoveryId. This call is not billed.

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.

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.

Submit the task

Call generate_image. The result contains taskId and a status of pending, success, or failure.

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.

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. If the cause is a request error, correct the parameters and submit another task. For any other cause, contact CometAPI 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 <task_id> with the task ID:

set -o pipefail
curl -fsS "https://api.cometapi.com/v1/images/generations/<task_id>" \
  -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.

Start here

Model API quickstarts

Core API guides

Developer tools

Errors

Pricing and billing

Support

Find a model

Generate text

Use a receipt for a long generation

Generate an image

Save the image as a file

Errors

​Find a model

​Generate text

​Use a receipt for a long generation

​Generate an image

​Save the image as a file

​Errors

Find a model

Generate text

Use a receipt for a long generation

Generate an image

Save the image as a file

Errors