# Sakuranbo AI

> Sakuranbo AI provides one HTTP API for text, image, and video generation models. These endpoints list the model catalog, estimate generation costs, run chat completions, generate and edit images, generate videos, follow background jobs, receive webhooks, and show the API key in use and the prepaid balance.

## Key facts

- Base URL: https://api.sakuranbo.ai/v1
- Listing models and estimating costs are public and need no API key. Generation, jobs, and the account endpoints need one, sent as Authorization: Bearer <API key>. A missing, invalid, revoked, or expired key returns 401.
- Prices are in USD. Each amount is returned as integer micro USD (1 USD = 1,000,000 micro USD) and as a decimal string.
- Errors share one JSON shape: error.message, error.type, error.code, error.param, error.request_id, error.doc_url, and optional error.details. A failure is never returned with HTTP 200.
- Responses carry an X-Request-Id header. Send your own X-Request-Id (8 to 64 characters of A-Z, a-z, 0-9, _ or -) to correlate requests.

## Endpoints

- [List models](https://api.sakuranbo.ai/v1/models): GET. Optional query: modality, task, locale (en, ja, zh, ko).
- Get a model: GET https://api.sakuranbo.ai/v1/models/{vendor}/{model}
- Estimate a cost: POST https://api.sakuranbo.ai/v1/estimate with a JSON body { "model": "vendor/model", "input": {} }
- Get the API key in use (name, limit, usage): GET https://api.sakuranbo.ai/v1/key with an API key
- Get the prepaid balance: GET https://api.sakuranbo.ai/v1/balance with an API key
- Chat, OpenAI compatible: POST https://api.sakuranbo.ai/v1/chat/completions with an API key. Set the OpenAI SDK base URL to https://api.sakuranbo.ai/v1.
- Chat, Anthropic compatible: POST https://api.sakuranbo.ai/v1/messages with an API key, sent as Authorization: Bearer or x-api-key. Set the Anthropic SDK base URL to https://api.sakuranbo.ai.
- Generate images: POST https://api.sakuranbo.ai/v1/images/generations with an API key. It waits for the result; if that takes too long it returns 202 and a job.
- Edit images: POST https://api.sakuranbo.ai/v1/images/edits with an API key and reference images
- Generate a video: POST https://api.sakuranbo.ai/v1/videos with an API key. It answers 202 at once with a video; poll GET https://api.sakuranbo.ai/v1/videos/{id} until status is completed, then download it from GET https://api.sakuranbo.ai/v1/videos/{id}/content (a redirect to a signed URL). List with GET https://api.sakuranbo.ai/v1/videos, cancel with POST https://api.sakuranbo.ai/v1/videos/{id}/cancel.
- Get, list, or cancel jobs (images and videos): GET https://api.sakuranbo.ai/v1/jobs/{id}, GET https://api.sakuranbo.ai/v1/jobs, POST https://api.sakuranbo.ai/v1/jobs/{id}/cancel with an API key
- Webhooks (Standard Webhooks, signed POST requests): manage endpoints with POST https://api.sakuranbo.ai/v1/webhook-endpoints, GET, PATCH, and DELETE https://api.sakuranbo.ai/v1/webhook-endpoints/{id}. Send a test event, rotate the signing key, read the delivery log, and retry a delivery under the same path (see the OpenAPI). Events: job.succeeded, job.failed, job.cancelled, deposit.credited, balance.low.
- Get the measured availability and generation time of each model (no API key): GET https://api.sakuranbo.ai/v1/status. Numbers with fewer than 20 measured results are null.
- [Health check](https://api.sakuranbo.ai/healthz)

## MCP

- [Remote MCP server](https://api.sakuranbo.ai/mcp): Streamable HTTP. Tools: search_docs, get_doc, list_models, get_model, estimate_cost (no account data), and get_balance, get_usage, list_requests, list_jobs, get_job (the account of the token). All tools are read-only.
- Authentication: OAuth 2.1 (authorization server metadata: https://app.sakuranbo.ai/.well-known/oauth-authorization-server, protected resource metadata: https://api.sakuranbo.ai/.well-known/oauth-protected-resource/mcp), or an API key sent as Authorization: Bearer <API key>.
- [MCP documentation](https://sakuranbo.ai/docs/mcp/)

## Reference

- [OpenAPI 3.1](https://api.sakuranbo.ai/openapi.json)
- [API reference](https://api.sakuranbo.ai/reference)
- [API catalog (RFC 9727)](https://api.sakuranbo.ai/.well-known/api-catalog)
- [Documentation](https://sakuranbo.ai/docs)
- [Model catalog for people](https://sakuranbo.ai/models/)