# Quickstart Modelfy creates product photos: a product worn or held by a model in a real place, or the product alone on a studio background. This MCP server lets any AI agent do it for a person, with their Modelfy account and their credits. ``` https://mcp.modelfy.ai/mcp ``` Streamable HTTP. Sign-in with OAuth 2.1 (chat assistants) or a Bearer API key (bots and code). ## 1. Connect In Claude Code: ```sh claude mcp add --transport http --scope user modelfy https://mcp.modelfy.ai/mcp ``` Then run `/mcp`, pick `modelfy` and sign in with your Modelfy account. Other clients (claude.ai, ChatGPT, Cursor, VS Code, Codex, Antigravity, Zed, Cline, your own agent) are in [Connect your agent](https://mcp.modelfy.ai/docs/connect.md). No account yet? Get a free sandbox key and use it as a Bearer token. Nothing is spent and the photos are samples: ```sh curl -X POST https://mcp.modelfy.ai/sandbox/keys ``` ## 2. Ask for photos > Make 4 photos of this dress, vertical, on a model in a café: https://shop.example.com/dress.jpg The agent adds the product photos, picks a model and a place, and plans the session. ## 3. Say yes to the price The agent shows the exact price in credits before anything is spent. After your yes it launches the session, waits, and shows the photos when they are ready. See [Credits and consent](https://mcp.modelfy.ai/docs/credits.md). ## The tools | Tool | What it does | Spends credits | | -------------------------------------------------------- | -------------------------------------------------------------------------- | -------------- | | `get_account` | Balance, plan, price per photo; for live keys the budget and today's spend | no | | `list_models` · `list_backgrounds` · `get_photo_options` | People, places, formats, shot types | no | | `add_product_photos` | Product photos from public image links | no | | `create_upload_session` · `get_uploaded_photos` | Photos from code (presigned PUT) or from a page a person opens | no | | `plan_photos` | Plans a session; returns the exact price and a `quote_id` | no | | `generate_photos` | Launches the planned session | **yes** | | `get_photo_session` | Progress and finished photos; can wait until done | no | | `list_recent_photos` · `cancel_photo_session` | Recent photos; stop a session (unstarted photos are refunded) | refunds | | `get_docs` | These pages | no | Next: [Create photos](https://mcp.modelfy.ai/docs/photos.md) for the whole workflow, [Keys and sign-in](https://mcp.modelfy.ai/docs/keys.md) for every way to authenticate, [Errors](https://mcp.modelfy.ai/docs/errors.md) for what each error code means. --- # Connect your agent ``` https://mcp.modelfy.ai/mcp ``` Every client needs only that URL. How you sign in: - **OAuth (recommended):** the client opens the Modelfy web, you sign in once and allow it. Nothing to copy, and you are not asked again. See [Keys and sign-in](https://mcp.modelfy.ai/docs/keys.md#oauth). - **API key:** for clients without OAuth, and for bots. Send `Authorization: Bearer mfy_live_…` (or a free `mfy_test_…` sandbox key). See [Keys and sign-in](https://mcp.modelfy.ai/docs/keys.md). To check it works, ask your agent: _"What's my Modelfy balance?"_ It should call `get_account`. ## Claude Code ### The usual way ```sh claude mcp add --transport http --scope user modelfy https://mcp.modelfy.ai/mcp ``` Then, inside Claude Code, run `/mcp`, pick `modelfy` and sign in in the browser. From a shell, `claude mcp login modelfy` does the same. Tokens refresh on their own. `--scope user` makes it available in all your projects. Leave it out to add it to the current project only, or use `--scope project` to write a `.mcp.json` your team shares (each person signs in with their own account). With an API key instead of OAuth: ```sh claude mcp add --transport http --scope user modelfy https://mcp.modelfy.ai/mcp \ --header "Authorization: Bearer mfy_live_…" ``` ### Optional: the plugin The plugin brings the same server plus a skill that teaches Claude the whole photo workflow: what to ask the person, when to ask before spending, how to upload local files, and what to do after each error. ``` /plugin marketplace add brookmind/modelfy-mcp /plugin install modelfy@modelfy ``` The plugin includes the server, so you do not need `claude mcp add` too (if you already added it, `claude mcp remove modelfy` avoids two copies). In `/mcp` it shows as `plugin:modelfy:modelfy`; sign in there. ## claude.ai and Claude Desktop 1. **Customize** → **Connectors** → **+ Add** → **Add custom connector**. 2. Name: `Modelfy`. URL: `https://mcp.modelfy.ai/mcp`. 3. Keep the default sign-in and OAuth client options, and add it. Sign in with your Modelfy account when asked. 4. In a conversation, turn it on from **+** → **Connectors**. Custom connectors are available on Free (one connector), Pro, Max, Team and Enterprise. On Team and Enterprise an owner adds it in **Organization settings** → **Connectors**, and each member then clicks **Connect**. Connectors you add on claude.ai also work in Claude Desktop. ## ChatGPT 1. Open [chatgpt.com/plugins](https://chatgpt.com/plugins) → **+** → **Add custom MCP server**. 2. Name: `Modelfy`. Server URL: `https://mcp.modelfy.ai/mcp`. Authentication: **OAuth**. 3. Accept the warning, **Create**, and install it. Sign in with your Modelfy account. 4. In a chat, call it with `@Modelfy`. ChatGPT connects with OAuth only (no API key field), on the web. Custom MCP servers depend on your plan and, in workspaces, on an admin setting; some accounts need **Developer mode** in Settings. ## Cursor [Add to Cursor](https://cursor.com/install-mcp?name=modelfy&config=eyJ1cmwiOiJodHRwczovL21jcC5tb2RlbGZ5LmFpL21jcCJ9) (one click), or add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "modelfy": { "url": "https://mcp.modelfy.ai/mcp" } } } ``` Cursor asks you to sign in the first time it uses the server. With an API key, add `"headers": { "Authorization": "Bearer ${env:MODELFY_API_KEY}" }` and set `MODELFY_API_KEY` in your environment. ## VS Code (GitHub Copilot) Run **MCP: Add Server** from the Command Palette, choose **HTTP**, paste `https://mcp.modelfy.ai/mcp`, name it `modelfy` and save it to **Copilot Global**. Or write `~/.copilot/mcp-config.json`: ```json { "mcpServers": { "modelfy": { "type": "http", "url": "https://mcp.modelfy.ai/mcp", "tools": ["*"] } } } ``` Then click **Authenticate** in the server's actions and sign in. With an API key, add `"headers": { "Authorization": "Bearer ${MODELFY_API_KEY}" }` (the braces are required). ## Codex (CLI and IDE extension) ```sh codex mcp add modelfy --url https://mcp.modelfy.ai/mcp ``` Codex starts the sign-in right away. To sign in again later: `codex mcp login modelfy`. With an API key kept in an environment variable: ```sh codex mcp add modelfy --url https://mcp.modelfy.ai/mcp --bearer-token-env-var MODELFY_API_KEY ``` Both write `~/.codex/config.toml`, which the CLI and the IDE extension share: ```toml [mcp_servers.modelfy] url = "https://mcp.modelfy.ai/mcp" # bearer_token_env_var = "MODELFY_API_KEY" # only with an API key ``` In the IDE extension you can also use the gear → **MCP servers** → **Add server** → **Streamable HTTP**, then **Authenticate**. ## Antigravity (formerly Gemini CLI) Add this to `~/.gemini/config/mcp_config.json` (all workspaces) or `.agents/mcp_config.json` (one workspace), then run `/mcp` in the CLI to reload: ```json { "mcpServers": { "modelfy": { "serverUrl": "https://mcp.modelfy.ai/mcp" } } } ``` Sign-in starts on its own the first time. With an API key, add `"headers": { "Authorization": "Bearer mfy_live_…" }`. ## Zed In your settings, under `context_servers`: ```json { "context_servers": { "modelfy": { "url": "https://mcp.modelfy.ai/mcp" } } } ``` Without an `Authorization` header Zed signs you in with OAuth; with an API key, add `"headers": { "Authorization": "Bearer mfy_live_…" }`. ## Cline In **MCP Servers** → **Remote Servers**, or in `cline_mcp_settings.json`: ```json { "mcpServers": { "modelfy": { "type": "streamableHttp", "url": "https://mcp.modelfy.ai/mcp", "headers": { "Authorization": "Bearer mfy_live_…" } } } } ``` ## Your own agent or bot First get a key: a free [sandbox key](https://mcp.modelfy.ai/docs/keys.md#sandbox-keys) to build and test, then a live key with [device login](https://mcp.modelfy.ai/docs/keys.md#device-login) (nobody copies it) or [by hand](https://mcp.modelfy.ai/docs/keys.md#api-keys-by-hand). Then pick one of these. ### Any MCP SDK TypeScript, with `@modelcontextprotocol/client`: ```ts import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client"; const client = new Client({ name: "store-bot", version: "1.0.0" }); await client.connect( new StreamableHTTPClientTransport(new URL("https://mcp.modelfy.ai/mcp"), { requestInit: { headers: { Authorization: `Bearer ${process.env.MODELFY_API_KEY}` }, }, }), ); const account = await client.callTool({ name: "get_account", arguments: {} }); ``` Read `client.getInstructions()` once: the server sends its workflow and spending rules there. ### Anthropic Messages API (Claude) The API connects to the server for you. The token goes in `authorization_token`, without `Bearer`: ```sh curl https://api.anthropic.com/v1/messages \ -H "content-type: application/json" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "anthropic-beta: mcp-client-2025-11-20" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{ "role": "user", "content": "What is my Modelfy balance?" }], "mcp_servers": [{ "type": "url", "url": "https://mcp.modelfy.ai/mcp", "name": "modelfy", "authorization_token": "mfy_live_…" }], "tools": [{ "type": "mcp_toolset", "mcp_server_name": "modelfy" }] }' ``` ### OpenAI Responses API The token goes in `authorization`, without `Bearer`, on every request. With a live key its budget limits what the bot can spend; use `"require_approval": "always"` if a person should approve each call: ```json { "model": "gpt-6-astra", "input": "What is my Modelfy balance?", "tools": [ { "type": "mcp", "server_label": "modelfy", "server_url": "https://mcp.modelfy.ai/mcp", "authorization": "mfy_live_…", "require_approval": "never" } ] } ``` ### xAI API (Grok) `POST https://api.x.ai/v1/responses`: ```json { "model": "grok-4.7", "input": [{ "role": "user", "content": "What is my Modelfy balance?" }], "tools": [ { "type": "mcp", "server_label": "modelfy", "server_url": "https://mcp.modelfy.ai/mcp", "headers": { "Authorization": "Bearer mfy_live_…" } } ] } ``` ### Any other client If it speaks MCP over Streamable HTTP, give it the URL: it either signs in with OAuth (discovered from the server's `401`) or sends the `Authorization: Bearer` header. --- # Keys and sign-in Every request to `https://mcp.modelfy.ai/mcp` carries `Authorization: Bearer `. There are four ways to get one. | Way | Token | For | Spends credits | | ------------------------------------ | ---------------------------- | ----------------------------------------------------------------------- | ------------------------------ | | [OAuth](#oauth) | issued by the server | claude.ai, Claude Desktop, ChatGPT, Claude Code, Codex, Cursor, VS Code | yes, after the person's yes | | [Sandbox key](#sandbox-keys) | `mfy_test_…` | trying the server, building an integration, no account | never | | [Device login](#device-login) | `mfy_live_…` or `mfy_test_…` | coding agents and bots that need their own key | live keys, within their budget | | [API key by hand](#api-keys-by-hand) | `mfy_live_…` or `mfy_test_…` | anyone who prefers to paste a key | live keys, within their budget | ## OAuth Clients that support MCP authorization find everything on their own: the server answers `401` with a `WWW-Authenticate` header that points to `/.well-known/oauth-protected-resource`, and the authorization server supports dynamic client registration, client ID metadata documents and PKCE. The person signs in on the Modelfy web once and allows the assistant. After that: - Access tokens last one hour and the client refreshes them silently. - Refresh tokens have no fixed end; they expire only after 90 days without use. - Each device keeps its own connection, so signing in on a laptop does not sign out the phone. The person sees every connected assistant in their Modelfy account (Account, _AI assistants and API keys_) and can disconnect any of them. ## Sandbox keys ```sh curl -X POST https://mcp.modelfy.ai/sandbox/keys ``` ```json { "api_key": "mfy_test_…", "expires_at": "2026-12-15T10:00:00.000Z" } ``` A free key with no account, valid for 30 days. Every tool works: the catalog is real, everything else is canned, the photos are samples marked SANDBOX, and nothing is spent. Limits: 5 keys per hour per address and one request every 10 seconds (an IPv6 address counts as its /64), 60 calls per minute per key. There is also a daily total of free keys for everyone; when it is used up the answer is `429` until 00:00 UTC, and device login still works. ### Try the spending rules By default a sandbox key launches without asking anyone. To try the flow your agent will really have, ask for a key that spends like one: ```sh curl -X POST https://mcp.modelfy.ai/sandbox/keys \ -H "Content-Type: application/json" \ -d '{"acts_as": "person"}' ``` | `acts_as` | Behaves like | What changes | | ---------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `"person"` | an OAuth connection in a chat | `generate_photos` needs `user_confirmed: true` after the person's yes, or returns `CONFIRMATION_REQUIRED` | | `"bot"` | a live key with the default budget | 100 credits per photo session and 500 per UTC day (20 credits per photo); a launch over it returns `BUDGET_EXCEEDED`; `get_account` shows the budget | The sandbox's daily budget is approximate when several launches start at the same moment; the real budget of a live key is exact. ### A demo product `https://mcp.modelfy.ai/sandbox/demo/product` is a small product page (a linen T-shirt with two photos) to try "make photos of this product" without a store of your own. Its image links work with `add_product_photos`; the page itself is not an image and comes back as rejected, like any web page. ## Device login For an agent that runs in a terminal or on a server ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)). Nobody copies a key: the person approves in the browser and the key goes straight to the agent. **1. Start.** `client_name` is what the person will see. ```sh curl -X POST https://mcp.modelfy.ai/device/code \ -H "Content-Type: application/json" \ -d '{"client_name": "Store bot"}' ``` ```json { "device_code": "…", "user_code": "BCDF-GHJK", "verification_uri": "https://beta.modelfy.ai/activate", "verification_uri_complete": "https://beta.modelfy.ai/activate?code=BCDF-GHJK", "expires_in": 600, "interval": 5 } ``` **2. Show the person the link** (`verification_uri_complete`) and the code. They sign in, check the code and choose a test key, or a live key with a credit budget. **3. Poll** every `interval` seconds until the answer is not `authorization_pending`: ```sh curl -X POST https://mcp.modelfy.ai/device/token \ -H "Content-Type: application/json" \ -d '{"device_code": "…"}' ``` | Answer | Meaning | Do | | -------------------------------------------------------------- | ------------------ | ----------------------------------------------------- | | `200 {"api_key": "mfy_live_…", "kind": "live", "budget": {…}}` | Approved | Store the key as a secret; use it as the Bearer token | | `400 {"error": "authorization_pending"}` | Not approved yet | Wait `interval` seconds and poll again | | `400 {"error": "slow_down"}` | Polling too fast | Add 5 seconds to the interval | | `400 {"error": "access_denied"}` | The person said no | Stop | | `400 {"error": "expired_token"}` | 10 minutes passed | Start again | The key is delivered once. The server limits device codes to 10 per hour per address and one request every 10 seconds (an IPv6 address counts as its /64). Over that limit, `POST /device/code` answers `429 {"error": "rate_limited"}` with a `Retry-After` header: wait that many seconds before starting again (`slow_down` is only for polling `/device/token`). ## API keys by hand In the Modelfy web: Account, _AI assistants and API keys_, **Create key**. Pick test or live; a live key gets a budget per photo session and per day (default 100 and 500 credits). The key is shown once. Send it as `Authorization: Bearer mfy_live_…`. A person can have up to 20 keys, change a key's budget at any time, and revoke a key; anything using it stops at once. ## Which kind of key is this? `get_account` returns `keyKind` and `sandbox`, and says in words which key it is: | `keyKind` | What it is | `sandbox` | | ----------- | --------------------------------------------- | --------- | | `anonymous` | A sandbox key of no account (`/sandbox/keys`) | `true` | | `test` | A test key of a person's Modelfy account | `true` | | `live` | A person's API key that spends their credits | `false` | | `oauth` | A person's connection from a chat assistant | `false` | A test key from device login or the Modelfy web is the person's own key even though `sandbox` is `true`: keep it. The server's instructions on connect also change with the kind: for example, OAuth connections must ask the person before spending. --- # Create photos ``` product photos in → choices → plan_photos → generate_photos → get_photo_session (free) (free) (free, price) (spends) (free) ``` ## 1. Product photos in Every session starts from photos of the product: the front first, and optionally one detail. Each tool returns `upload_id`s for `plan_photos`. **From links** (the store's product images, a CDN): `add_product_photos` with up to 10 `image_urls`. Each link must be the image file itself, not a web page. JPEG, PNG, WebP or HEIC, up to 15 MB. Each link succeeds or fails on its own: ```json { "photos": [ { "source_url": "https://shop.example.com/dress.jpg", "upload_id": "…" }, { "source_url": "https://shop.example.com/page", "error": "Not an image" } ] } ``` **From files**, with `create_upload_session` (up to 10 files, valid one hour): - _An agent with code_ (Claude Code, Codex, a bot) announces each file and sends the bytes itself to the presigned URL. Never pass image bytes through the model as base64. ```json { "files": [{ "content_type": "image/jpeg", "bytes": 482113 }] } ``` ```sh curl -X PUT "" -H "Content-Type: image/jpeg" --data-binary @dress.jpg ``` Send exactly the `headers` the tool returned for that upload. - _A chat assistant_ (claude.ai, ChatGPT) calls it with no files and gives the person `page_url`: a Modelfy page where they drop the photos from their computer or phone. Then `get_uploaded_photos` with the `session_id`: ready `upload_id`s, files still pending, and rejected files with the reason. Call it again while `pending` is above zero. ## 2. Choices | Tool | Gives | Used in `plan_photos` as | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `list_models` | People who wear or hold the product (the account's own and Modelfy's). Only `ready: true` can be used. | `model_ids` (up to 3; leave empty for product-only photos) | | `list_backgrounds` | Real places (the account's own and Modelfy's gallery) | `background_id`, or describe a place in `place_description` | | `get_photo_options` | Aspect ratios, photos per product (min, max), shot types, resolutions and qualities (they change the price), outfit styles | `aspect_ratio`, `photos_per_product`, `shot_types`, `resolution`, `quality`, `outfit` | Never invent an id. Use only ids these tools returned in this conversation. ## 3. Plan `plan_photos` checks everything and returns the exact price. Nothing is spent. ```json { "products": [ { "upload_ids": ["", ""], "name": "Linen dress" } ], "mode": "place", "model_ids": [""], "place_description": "a sunny café terrace in the morning", "aspect_ratio": "4:5", "photos_per_product": 4, "direction": "relaxed, natural light", "locale": "en" } ``` - `mode`: `place` (a real place: `background_id` or `place_description`) or `studio` (a plain background; `background_color` in words, like "light grey"). - `aspect_ratio` and `photos_per_product` are always required. If the person did not say, ask; do not pick for them. - `direction`: the person's own words about the look. - `locale`: the person's language. The answer has `quote_id` (valid 30 minutes), `credits`, `photos`, `enough_credits`, `balance`, and for live keys `budget`. ## 4. Launch `generate_photos` with the `quote_id`. In a chat, first show the person the credits and ask; only after their yes call it with `user_confirmed: true`. See [Credits and consent](https://mcp.modelfy.ai/docs/credits.md). Calling it again with the same `quote_id` returns the same session; it never charges twice. ## 5. Wait and show `get_photo_session` with `session_id` and `wait_seconds` (up to 45) waits until the session finishes. If it is still `running`, call it again. When done, it returns every photo's link (`url`, full size) and a `preview_url` (a small JPEG, when Modelfy has one), and up to four of them as images the chat can show (the preview, or the photo itself when it is under 1 MB). | Status | Meaning | | ----------- | ------------------------------------------------------------------- | | `running` | Photos are being made | | `completed` | All photos are ready | | `partial` | Some photos failed; their credits were refunded | | `failed` | No photo could be made; everything was refunded | | `cancelled` | Stopped with `cancel_photo_session`; unstarted photos were refunded | Show the photos, or the session's `web_url` where the person can see and download them all. ## Later - `list_recent_photos`: the latest photos of the account, or of one session. - `cancel_photo_session`: stops a running session. Finished photos stay. --- # Credits and consent Photos cost credits from the person's Modelfy account. The server makes sure no credit is spent without consent: a person's yes in a chat, or a budget the key's owner set. ## Every launch is quoted first `plan_photos` returns the exact price (`credits`) and a `quote_id`. The server keeps that exact plan for 30 minutes, bound to the connection that made it. `generate_photos` launches only a quote: the agent cannot change the plan or the price between the person's yes and the launch. The quote is also the idempotency key. A retry of `generate_photos` with the same `quote_id` (after a timeout, say) returns the session already launched and never charges twice. ## Who must agree | Connection | Before `generate_photos` | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OAuth (a person in a chat) | Show the price and ask. Call it with `user_confirmed: true` only after the person said yes to that exact price, after seeing it: a "just do it, no need to ask" said before the price is not a yes. Without it the server answers `CONFIRMATION_REQUIRED`. | | Live API key | No confirmation needed: the key's budget is the consent. If a person is in the conversation, still show the price and ask. | | Test or sandbox key | Nothing is spent. | A good question to the person: "4 photos for 80 credits (you have 880). Go ahead?" ## Live key budgets Each live key has two limits, set by its owner in the Modelfy web: - **Per photo session**: the most one launch can cost. - **Per day**: the most the key can spend in a UTC day. Modelfy checks both inside the same database transaction that reserves the credits, so two launches at once cannot go over. A launch that would go over fails with `BUDGET_EXCEEDED` and spends nothing; the error carries the budget and today's spend. `get_account` shows `budget.spentToday` and `budget.resetsAt`; `plan_photos` shows `budget.session_limit` and `budget.left_today` next to the price. A job bigger than the budget per session is still allowed within the daily budget: split it into smaller sessions (fewer photos or products each) and launch them one at a time. When a plan is over the per-session budget, `plan_photos` says how many photos fit in one session. ## Refunds - Photos that fail are refunded automatically. - `cancel_photo_session` refunds photos that had not started. - `get_photo_session` shows `credits.reserved`, `credits.charged` and `credits.refunded`. ## Not enough credits `plan_photos` returns `enough_credits: false` before anything is tried, and a launch without enough credits fails with `INSUFFICIENT_CREDITS`. The person can buy credits or change plan at https://beta.modelfy.ai/plans. --- # Errors A tool that fails returns `isError: true` with one sentence for the model and this JSON: ```json { "error": { "code": "BUDGET_EXCEEDED", "message": "This launch would go over the key's daily budget.", "next_step": "Over the budget per photo session: plan smaller sessions (fewer photos or products each) and launch them one at a time. Over the daily budget: wait until it resets (budget.resetsAt) or ask the key's owner to raise it.", "docs_url": "https://mcp.modelfy.ai/docs/errors#BUDGET_EXCEEDED" } } ``` `code` is stable: branch on it, not on the message. Follow `next_step`. ## Tool errors ### CONFIRMATION_REQUIRED An OAuth connection called `generate_photos` without `user_confirmed: true`. Nothing was spent. Show the person the price from `plan_photos` and call again with `user_confirmed: true` only if they agree. ### INSUFFICIENT_CREDITS The account does not have enough credits. Tell the person; they can buy credits or change plan at https://beta.modelfy.ai/plans. Or plan fewer photos. ### BUDGET_EXCEEDED The launch would go over the live key's budget per session or per day. Nothing was spent. The error includes `budget` (`limit` says which one). Over the budget per session, the job still fits: plan smaller sessions (fewer photos or products each, within `budget.maxCreditsPerSession`) and launch them one at a time; `plan_photos` already says how many photos fit in one session. Over the daily budget: wait until it resets (`budget.resetsAt`), or ask the key's owner to raise it in the Modelfy web. See [Credits and consent](https://mcp.modelfy.ai/docs/credits.md). ### QUOTE_EXPIRED The `quote_id` does not exist or is older than 30 minutes. Call `plan_photos` again and use the new `quote_id`. If the price changed, ask the person again. ### QUOTE_NOT_YOURS The quote was made by another connection. Call `plan_photos` with this connection. ### MISSING_CHOICE `plan_photos` lacks a choice the session needs: for example `mode: "place"` with neither `background_id` nor `place_description`. The message names it. Ask the person, or use the catalog tools, then plan again. ### INVALID_INPUT An input was refused (an unknown id, a format not in `get_photo_options`, a model that is not ready). Fix it as the message says and call again. Never guess ids: list them again. ### NOT_FOUND The id does not exist for this account (a session, an upload). List the items again to get a valid one. ### PHOTO_REJECTED A product photo link could not be used: it is not public, it is not an image file (JPEG, PNG, WebP, HEIC), it is over 15 MB, or the upload to Modelfy failed. `add_product_photos` does not fail for this: the call succeeds, and each link that could not be used comes back with an `error` message next to its `source_url` instead of an `upload_id`. Use a public https link to the image file itself, or upload the file with `create_upload_session`. ### CONNECTION_REVOKED The connection was revoked or expired: the person disconnected the assistant or revoked the key. For OAuth, the client signs in again on the next request. For an API key, ask the person for a new one or use [device login](https://mcp.modelfy.ai/docs/keys.md#device-login). ### RATE_LIMITED Too many requests. Wait a minute and try again. ### MODELFY_ERROR Modelfy could not complete the request. Try again in a moment; if it keeps failing, tell the person. Retrying `generate_photos` with the same `quote_id` is always safe. ## HTTP errors of the endpoint | Status | Body | Meaning | | ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `401` | `{"error": "invalid_token"}` | Missing, wrong, expired or revoked token. OAuth clients refresh or sign in again; with an API key, check it. | | `429` | `{"error": "rate_limited"}` | An anonymous sandbox key made more than 60 calls in a minute. Wait a minute, or get your own key with device login. |