---
name: kerox
description: Integrate Kerox image and video generation into an app or use Kerox MCP to estimate, submit, and track generation tasks.
---

# Kerox

Use the REST API at `https://api.kerox.ai/v1` when writing application code. Use the remote MCP at `https://api.kerox.ai/mcp` when operating Kerox from an MCP client. Use `Authorization: Bearer $KEROX_API_KEY` for authenticated requests. Keep the key in a server-side environment variable. REST model discovery also works anonymously and returns public pricing.

If the MCP server is missing, use the bundled [mcp.json](mcp.json) as a client configuration template. See the [MCP setup guide](https://kerox.ai/docs/mcp.md).

## Generate an image or video

| Step | REST | MCP |
| --- | --- | --- |
| Find a published model with status `live` | `GET /v1/models` | `list_models` |
| Read the current model schema | `GET /v1/models/{id}` | `get_model_schema` with `model` |
| Estimate the charge | `POST /v1/estimate` | `estimate` |
| Submit the generation | `POST /v1/tasks` | `create_task` |
| Read status and outputs | `GET /v1/tasks/{id}` | `get_task` with `id` |

1. Build the payload with `model` and `input` from the model's live `input_schema`. Native parameters are the default. Set `format: "unified"` only if the model reports `unified.supported`, and use its mapping for accepted fields.
2. Estimate with the exact model, input, and format you intend to submit. The returned `amount` in USD is the amount reserved at submission. If `exact` is false, the final charge can differ. Check available funds via `GET /v1/account` or `get_balance` when needed. Before an agent submits a live generation, confirm the cost is covered by the user's authorization.
3. Assign one unique idempotency key per intended task. Send it as the `Idempotency-Key` HTTP header or MCP `idempotency_key`. Within the 24-hour window, retry an ambiguous submission with the same key and payload. A conflict means the key was used with a different payload. After the window, reconcile task history before resubmitting.
4. Save the task ID. Poll while the status is `queued` or `running`, using bounded backoff. For short tasks, `wait_seconds` (0–60) can reduce polling. A response that is still in progress uses the same task ID. Stop on `succeeded`, `failed`, or `canceled`.
5. On success, read `output.images` or `output.videos` and the settled cost. Persist files you need before `expires_at`. On failure, inspect the task's `error.code` and `error.retryable` before considering a new generation.

## References

- Use the [quickstart](https://kerox.ai/docs/quickstart.md) for REST examples and the [OpenAPI schema](https://api.kerox.ai/openapi.json) for request and response types.
- For reference files, follow the [upload guide](https://kerox.ai/docs/files.md). With MCP, call `upload_file`, PUT the bytes to `upload_url` with `upload_headers`, then use the returned `url` in the model input.
- For callbacks, follow the [webhook guide](https://kerox.ai/docs/webhooks.md) to verify Standard Webhooks signatures over the raw request body and deduplicate deliveries by `webhook-id`.
- For HTTP failures, branch on the structured `error.code` and keep `request_id` for support. Honor `Retry-After` on HTTP 429 when present. See the [error catalog](https://kerox.ai/docs/errors.md).
