Manejar Homotope desde un agente de IA

This page is the playbook for an AI agent (Claude Code, Claude, ChatGPT, Gemini CLI, or a script) that uses Homotope through its MCP server at https://homotope.app/mcp. The raw text is at /en/agents.md. Every vectorize_image call is a job counted against the user’s account; every other tool is free. So look before you compute again.

1. Suggest. Call suggest_preset with the image (image_base64, image_url or source_job_id). It is free and computes nothing. Or pass "preset":"auto" to vectorize_image.
2. Compute. Call vectorize_image with that preset. For a sticker, a window sticker or a die-cut print, add cut_contour with the real width_mm (its margins are in mm at that size). It answers at once with a job_id: poll get_job until done (or failed). This is the only step that counts.
3. See and check. Call get_preview ("side":"both" compares with the original; zoom frames a box of the cut check or the part the user complained about), then check_cut with the real width_mm (and the printer’s safety_mm and spacing_mm if they gave them). Read report.blocking, printer.status and advice.
4. Correct with the advice. Take the first advice entry and compute again from the same source (source_job_id: no new upload), then go back to step 3. How to apply each kind of advice is below.

• setting is an engine setting (tolerance, smoothing, noise, colors…): pass it in options with its value (or one step in its direction), with the concrete preset (preset_suggested.preset from get_job if you used "auto", which takes no options).
• setting is contour: a number is the new cut_contour.margin_mm, a word is the new cut_contour.mode.
• setting is width_mm: the scale is unknown. Ask the user for the real width and call check_cut again: no new job is needed.
• setting is none: nothing in Homotope fixes it (the source, the layout or the printer’s file must change). Tell the user the why text and stop computing.

• Stop when check_cut passes (report.blocking is 0 and printer.status is ok; warn only if the user accepts it) AND the zoomed get_preview no longer shows the defect the user named.
• At most 3 jobs per image. After the last one, show the best result and the remaining advice instead of computing again.
• Stop at once on an advice with none, on a 402, or on a 429 too_many_variants.

• Each vectorize_image is one job: one of the free plan’s 2 trial jobs of the month (the same as in the web app), then the Pro quota (100 jobs a month), then one credit. A failed job is refunded.
• 402 payment_required: the account has no right left. The error carries purchaseUrl: give it to the user, do not retry, never quote a price (prices are on the Pricing page).
• 429 too_many_variants: more than 8 jobs of the same image in a rolling hour. retryAfterSeconds says when; meanwhile, look (get_preview, check_cut) rather than compute.
• 429 rate_limited (suggest_preset 30 a minute per API key or connection, get_preview 30 a minute per account) or too_many_jobs (queue full): wait retryAfterSeconds.
• The source image is kept 7 days. After that, source_job_id, the source side of get_preview and suggest_preset by job answer 410 source_expired: ask the user for the image again.
• get_preview: width up to 1024 px, 1 Mpx at most; zoom is in image pixels, the frame of the check_cut boxes.

• vectorize_image: one job (trial, Pro quota or credit).
• suggest_preset, get_preview, check_cut and its advice, read_printer_template: free, nothing written.
• get_job, get_svg, get_result, list_vectorizations: free; the formats of a finished job come with the job.

• get_result with "format":"pdf", the real width_mm (a 1:1 file, what printers ask for) and bleed_mm (often 2 mm). A job submitted with cut_contour carries a CutContour spot-colour layer; white_underprint and finish_layers add the printer’s white and finishing layers.
• DXF for a cutter: "format":"dxf" (one layer per colour), cut_only for the CutContour alone; layers gives colour separations.
• The printer sent a template PDF? read_printer_template (pdf_url or base64, free, nothing kept) returns its trim size, bleed and safety zone: copy them into get_result as page_width_mm, page_height_mm, bleed_mm and safe_mm (same_pages 2: front and back, verso_job_id). The user drew their own cut line? Pass it to vectorize_image as cut_contour_image_url (or base64) instead of cut_contour. get_preview takes white_underprint and finish_layers to show those layers on the result.
• The printer part of check_cut needs width_mm: shapes within safety_mm of the cut line (default 3 mm), stickers closer than spacing_mm (default 4 mm), strokes under 0.25 pt, a single closed CutContour in single mode. Without width_mm these checks are “unavailable”, never passed.

The user wants a window sticker 1,400 mm wide with a cut contour and 2 mm bleed. Two jobs here; a third only if the second check still fails.

suggest_preset    {"image_url":"https://…/vitrine.png"}
      vectorize_image   {"image_url":"https://…/vitrine.png","preset":"auto",
                         "cut_contour":{"width_mm":1400}}
      get_job           {"job_id":"<id>"}            (until "done")
      get_preview       {"job_id":"<id>","side":"both","width":1024}
      check_cut         {"job_id":"<id>","width_mm":1400}
      vectorize_image   {"source_job_id":"<id>","preset":"<preset_suggested.preset>",
                         "cut_contour":{"width_mm":1400,"margin_mm":<advice value>}}
      check_cut         {"job_id":"<id2>","width_mm":1400}
      get_result        {"job_id":"<id2>","format":"pdf","width_mm":1400,"bleed_mm":2}

Claude Code: add the server, then sign in from /mcp (OAuth, the user’s Homotope account). A script uses an API key in the Authorization: Bearer header; never write a key into a prompt, a file or a repository.

claude mcp add --transport http homotope https://homotope.app/mcp