Gencow Tools for AI Coding Agents

Generate images with reference images from OpenCode or any MCP client, check credits, and use the Gencow LLM as an OpenCode model

Sign in with your Gencow account and your coding agent (OpenCode, or any client that supports remote MCP servers) can generate images and read your credit balance. Everything is billed to your own Gencow credits. A free plan works as long as the account has a balance.

This page is for people who use Gencow from an agent. To generate images inside a deployed app, use the SDK instead (see AI Engine); ai.image.generate() accepts referenceImages too.

Connect

Add the Tools server to opencode.json (project or global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gencow-tools": { "type": "remote", "url": "https://tools.gencow.com/api/mcp" }
  }
}
opencode mcp auth gencow-tools

The browser opens; sign in to Gencow and choose Allow. A consent screen that says "unverified app" is expected, because MCP clients register themselves dynamically. The connection can only generate images and read your balance. It cannot deploy apps or reach app data or billing.

Clients that cannot open a browser can use an access token instead: create one in the Dashboard under Account settings, Connected tools, and send it as Authorization: Bearer <token>. A token is shown once.

{ "mcp": { "gencow-tools": { "type": "remote", "url": "https://tools.gencow.com/api/mcp",
  "oauth": false, "headers": { "Authorization": "Bearer {env:GENCOW_TOOLS_TOKEN}" } } } }

Review or revoke connections in the Dashboard under Account settings, Connected tools. Revoking invalidates that connection's token immediately.

Tools

The agent sees three tools (in OpenCode they are named gencow-tools_image_generate, gencow-tools_image_status, and gencow-tools_account_credits).

Tool What it does Cost
image_generate Generates one image from a prompt, optionally guided by reference images Billed per call
image_status Checks a job by jobId, or gets a fresh download link Free
account_credits Returns your balance and plan Free

image_generate

Argument Required Description
prompt yes What to generate, up to 4,000 characters
size no auto (default), 1024x1024, 1024x1536, or 1536x1024
quality no low (default), auto, medium, or high
reference_images no Up to 5 base64 data URLs (see below)
clientRequestId no 8 to 64 characters (letters, digits, _, -). Reuse it when retrying so the image is not billed twice
inlineImage no Also return the image as an MCP image block. Large; use it only if the client cannot open links

Credits are reserved when the job is accepted, charged when it succeeds, and refunded if it fails. The image is made as a background job: the call waits up to about 45 seconds and returns a download link with a Markdown image tag, so the agent can show a preview in the chat. If the image is not ready in time the call returns a jobId (this is not an error); call image_status with it in about 10 seconds. Do not call image_generate again for the same image.

The download link is valid for 60 minutes. Save the file into your project if you want to keep it. The finished image is stored for 24 hours, and image_status returns a new link without billing you again.

Without a clientRequestId, every call is a new billed request. With one, a repeat returns the same job and is not charged twice, even if the Tools server restarted in between.

Reference images

Pass reference_images when the new image must stay consistent with existing ones, for example the same character, product, or visual style across several images.

{
  "prompt": "The same fox mascot, now waving at the camera, flat vector style",
  "reference_images": ["data:image/png;base64,iVBORw0KGgo..."]
}
  • Each entry is a base64 data URL of a PNG, JPEG, or WebP image (data:image/png;base64,...). The type must match the real file bytes.
  • At most 5 images and 20 MB in total after decoding.
  • Web URLs are not fetched. The server never downloads anything for you, so read the file yourself and encode it.
  • The images travel inside the tool call, so keep them small. Resize large pictures before sending them.
  • Each reference image adds input cost. A generous amount is reserved when the job is accepted; the final charge uses the actual usage reported for the request, and the unused part of the reservation is refunded.
  • If you reuse a clientRequestId with different images, the call is rejected as a different request; use a new clientRequestId.

Limits

Per user: 6 images per minute, 60 per hour, and 2 image_generate calls being accepted at the same time. The queue of waiting jobs follows the async image policy (by default 5 per user on Free, 50 on Pro, 200 on Scale). A job that waits in the queue for more than 15 minutes is cancelled and refunded.

Errors

Every error carries code, whether credits changed (creditsChanged), whether a retry can work (retryable), the next step (nextAction), and a requestId.

Code Meaning What to do
TOOLS_AUTH_REQUIRED The sign-in expired or was revoked Run opencode mcp auth gencow-tools again
TOOLS_SCOPE_INSUFFICIENT The connection lacks the needed permission Reconnect and approve it
TOOLS_ACCOUNT_RESTRICTED The account state does not allow this Follow the notice on the Dashboard account page
TOOLS_CREDITS_EXHAUSTED Not enough credits. Nothing was charged Add credits, then call again
TOOLS_RATE_LIMITED A limit was reached Retry after retryAfterSeconds
TOOLS_INVALID_PARAMS The input was not accepted (nothing charged). For reference_images, a file that does not match its declared type or more than 20 MB in total comes back with a message that names the problem. A web URL, a value that is not an image data URL, or more than 5 images is rejected by the tool before anything is sent Fix the arguments as the message says and call again
TOOLS_CONTENT_REJECTED The prompt was declined by the content policy. Reserved credits were released Change the prompt
TOOLS_PRICING_UNAVAILABLE The price could not be confirmed. Nothing was charged Retry in a minute
TOOLS_PROVIDER_FAILED The image service failed. Reserved credits were refunded Retry with the same clientRequestId
TOOLS_GATEWAY_TIMEOUT No answer in time. Whether you were charged is unknown Check account_credits, then retry with the same clientRequestId
TOOLS_IMAGE_EXPIRED The stored result is gone (24 hours), or a link expired Call image_generate again; the earlier charge is unchanged

Use the Gencow LLM as an OpenCode model

You can also use llm/code as an OpenCode model, billed to the same credits. Log in and run one command:

gencow login
gencow opencode setup

Restart OpenCode and choose gencow/llm/code. The command, its options, and its error codes are described in the CLI reference.

The LLM token can call only llm/code. Any other model returns TOOLS_MODEL_NOT_ALLOWED without a charge. A token without the LLM permission returns TOOLS_SCOPE_NOT_ALLOWED. If a call returns 401 invalid_api_key, run gencow opencode setup --force; for 402 insufficient_service_credits, add credits and retry.

Image attachments

llm/code accepts images. Paste an image into OpenCode or attach it with -f.

  • PNG, JPEG, WebP, or GIF; up to 5 images and 20 MiB in total per request. Remote image URLs are not accepted.
  • OpenCode resends the whole conversation on every turn, so once an image is in a session its tokens are charged again on every later turn. In a long session, start a new session when the image is no longer needed.
  • Rejected images are not charged: AI_IMAGE_COUNT_EXCEEDED (6 or more images, including images from earlier turns), AI_IMAGE_INPUT_TOO_LARGE (over 20 MiB), AI_IMAGE_MEDIA_TYPE_UNSUPPORTED (for example SVG or HEIC), and AI_IMAGE_URL_NOT_SUPPORTED (a remote URL).
  • If image attachments did not work with an older install, run gencow opencode setup again; it repairs the settings without creating a new token.

Keep the token private. It can spend your credits, so store it only in an environment variable or OpenCode's credential store, and revoke it under Connected tools in the Dashboard if you suspect a leak.