{"openapi":"3.1.0","info":{"title":"AutoFigure-Edit API","summary":"Async API for turning method text or existing images into editable SVG figures.","description":"AutoFigure-Edit provides a small set of async APIs for creating SVG generation jobs from method text or existing images, subscribing to progress via Server-Sent Events, and downloading artifacts such as `figure.png`, `template.svg`, `final.svg`, and `final_preview.png`.","version":"1.0.0"},"paths":{"/healthz":{"get":{"tags":["System"],"summary":"Health check","description":"Minimal endpoint to verify that the service, proxy, and container are working.","operationId":"healthz_healthz_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/config":{"get":{"tags":["System"],"summary":"Get frontend runtime config","description":"Returns frontend runtime information such as whether the built-in SVG editor is available and where it is mounted.","operationId":"get_config_api_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/run":{"post":{"tags":["Jobs"],"summary":"Create a generation job","description":"Returns a `job_id` immediately after submission; the actual generation runs asynchronously in the background.","operationId":"run_job_api_run_post","parameters":[{"name":"api_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/image-to-svg":{"post":{"tags":["Jobs"],"summary":"Convert an existing image to SVG","description":"Creates an async job from an already generated image. This endpoint skips image generation and starts from SAM segmentation plus SVG generation.","operationId":"image_to_svg_job_api_image_to_svg_post","parameters":[{"name":"api_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageToSvgRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/upload":{"post":{"tags":["Uploads"],"summary":"Upload a reference image (legacy-compatible)","description":"Legacy-compatible upload endpoint. Uploads one reference image, stores it on the server, and returns the old-style path information accepted by `/api/run`.","operationId":"upload_reference_api_upload_post","parameters":[{"name":"api_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_reference_api_upload_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/events/{job_id}":{"get":{"tags":["Jobs"],"summary":"Subscribe to the job event stream","description":"Receive real-time job status, logs, and artifact discovery events over Server-Sent Events.","operationId":"stream_events_api_events__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","description":"Job ID returned by `/api/run` or `/api/image-to-svg`.","title":"Job Id"},"description":"Job ID returned by `/api/run` or `/api/image-to-svg`."},{"name":"api_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/artifacts/{job_id}/{path}":{"get":{"tags":["Artifacts"],"summary":"Download a job artifact","description":"Download a generated file or intermediate file from a job directory by job ID and relative path.","operationId":"get_artifact_api_artifacts__job_id___path__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","description":"Job ID.","title":"Job Id"},"description":"Job ID."},{"name":"path","in":"path","required":true,"schema":{"type":"string","description":"Relative path inside the job directory, for example `final.svg`, `final_preview.png`, or `icons/icon_AF01_nobg.png`.","title":"Path"},"description":"Relative path inside the job directory, for example `final.svg`, `final_preview.png`, or `icons/icon_AF01_nobg.png`."},{"name":"api_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/uploads/{filename}":{"get":{"tags":["Uploads"],"summary":"Fetch an uploaded reference image (legacy-compatible)","description":"Legacy-compatible fetch endpoint for accessing reference images produced by the old upload flow.","operationId":"get_upload_api_uploads__filename__get","parameters":[{"name":"filename","in":"path","required":true,"schema":{"type":"string","description":"Uploaded filename, usually the last segment of the URL returned by `/api/upload`.","title":"Filename"},"description":"Uploaded filename, usually the last segment of the URL returned by `/api/upload`."},{"name":"api_token","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_upload_reference_api_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"Reference image file to upload. Only image formats are accepted."}},"type":"object","required":["file"],"title":"Body_upload_reference_api_upload_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImageToSvgRequest":{"properties":{"image_url":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Image URL","description":"Public HTTPS image URL to convert into an SVG. Use either image_url or image_path, not both."},"image_path":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Image Path","description":"Path returned by /api/upload. Use either image_url or image_path, not both."},"provider":{"type":"string","title":"Model Provider","description":"Main model provider used for SVG generation.","default":"openrouter"},"svg_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"SVG Provider","description":"Optional provider override for SVG generation."},"svg_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"SVG Model","description":"Optional override for the SVG generation model."},"sam_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Segmentation Prompt","description":"Segmentation prompt passed to SAM3, for example icon,person,robot,animal."},"sam_backend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"SAM Backend","description":"SAM3 backend, commonly fal, roboflow, or local. Defaults to fal.","default":"fal"},"sam_max_masks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Masks","description":"Optional upper limit for segmentation results returned by the SAM backend."},"placeholder_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Placeholder Mode","description":"Placeholder matching mode, commonly label or box."},"merge_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Merge Threshold","description":"Threshold used when merging overlapping SAM boxes."},"optimize_iterations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Optimization Iterations","description":"Number of optimization iterations to run after the initial SVG is generated."}},"additionalProperties":false,"type":"object","title":"ImageToSvgRequest"},"RunRequest":{"properties":{"method_text":{"type":"string","minLength":1,"title":"Method Text","description":"Paper method description or drawing instructions used as the main prompt."},"provider":{"type":"string","title":"Model Provider","description":"Main model provider. By default it is used for SVG generation; image generation defaults to KIE unless image_provider is changed.","default":"openrouter"},"image_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Provider","description":"Provider for step 1 image generation. Defaults to kie so the API can use KIE image models while keeping SVG generation on the main provider.","default":"kie"},"image_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Model","description":"Image model ID. For KIE, supported values are nano-banana-pro, gpt-image-2-text-to-image, and gpt-image-2-image-to-image. If omitted, KIE uses nano-banana-pro."},"image_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Size","description":"Image resolution, for example 1K, 2K, or 4K. KIE defaults to 1K. For GPT Image 2 models, aspect_ratio=auto only supports 1K and aspect_ratio=1:1 does not support 4K."},"image_aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Aspect Ratio","description":"Image aspect ratio. KIE nano-banana-pro defaults to 16:9. KIE GPT Image 2 models default to auto and support auto, 1:1, 5:4, 9:16, 21:9, 16:9, 4:3, 3:2, 4:5, 3:4, and 2:3."},"svg_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"SVG Provider","description":"Optional provider override for step 4 SVG generation."},"svg_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"SVG Model","description":"Optional override for the SVG generation model."},"sam_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Segmentation Prompt","description":"Segmentation prompt passed to SAM3, for example icon,person,robot,animal."},"sam_backend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"SAM Backend","description":"SAM3 backend, commonly fal, roboflow, or local. Defaults to fal.","default":"fal"},"sam_max_masks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Masks","description":"Optional upper limit for segmentation results returned by the SAM backend."},"placeholder_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Placeholder Mode","description":"Placeholder matching mode, commonly label or box."},"merge_threshold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Merge Threshold","description":"Threshold used when merging overlapping SAM boxes."},"optimize_iterations":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Optimization Iterations","description":"Number of optimization iterations to run after the initial SVG is generated."},"reference_image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Image URL","description":"Recommended option. Provide a public HTTPS image URL, typically hosted on R2. Official R2 domains are allowed by default; for custom domains use REFERENCE_IMAGE_ALLOWED_HOSTS."},"reference_image_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reference Image Path","description":"Legacy-compatible option. Use the path returned by /api/upload. New integrations should prefer reference_image_url."}},"additionalProperties":false,"type":"object","required":["method_text"],"title":"RunRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"System","description":"Endpoints for health checks and frontend runtime configuration."},{"name":"Jobs","description":"Async generation jobs and Server-Sent Events streams."},{"name":"Artifacts","description":"Read generated artifacts and intermediate files for a job."},{"name":"Uploads","description":"Upload and fetch optional reference images."}]}