Genarrative/.codex/skills/genarrative-external-editor-api/references/capability-routing.md

Capability Routing

Use this reference to translate user intent into a hosted MCP tool or its corresponding External v1 REST operation. Use genarrative://external-editor/openapi or GET /api/external/v1/openapi.json for exact schemas.

Integration Surface

• Fixed production base URL: https://www.genarrative.world/.
• Discovery manifest: GET /api/external/v1/agent-integration.json.
• Hosted MCP: /api/external/v1/mcp, Streamable HTTP, authenticated with the same Bearer API Key as REST.
• Public contract: GET /api/external/v1/openapi.json.
• Skill fallback: GET /api/external/v1/skill/SKILL.md or GET /api/external/v1/skill.zip.

Prefer MCP when the Agent supports a remote endpoint plus a custom Bearer token. Prefer the complete Skill and Python helper when MCP is unavailable or a client-side local-file upload must be orchestrated. Choose a task-oriented tool below for ordinary requests, or the corresponding operation tool in API Operations when the request needs direct control of one REST call. All 44 tools remain available. Discover the live tool schema before calling it; OpenAPI remains the field-level authority. The public discovery and Skill download routes are listed below, but are not MCP tools.

Project and Asset Destination

Use find_canvas_projects (action=list, recent, or get) to locate an existing canvas when the request involves one. Use manage_canvas_projects (create or rename) only when the user needs a project created or renamed. A new project does not create an asset folder automatically. Use find_assets and organize_asset_library when the task involves library records or folders. A project and folder may have different names, and either may be unnecessary for a standalone generation.

For generation, pass projectId with canvasCompletion when the result should enter a canvas, and assetFolderId with the endpoint's label field when it should enter the library. Use both only when the task requires both destinations. Character animation returns its final resource and asset directly when those destinations are requested; do not duplicate its first frame.

Art Spec Routing

For a series of related art requests, an optional reusable spec can carry the shared requirements:

{
  "assetType": "character | background | prop | ui | icon | animation | video | audio",
  "subject": "要生成的主体",
  "style": "画风、材质、时代或参考风格",
  "palette": "主色与禁用色",
  "composition": "构图、镜头、姿态或布局",
  "format": "比例、尺寸、分辨率、帧数或时长",
  "constraints": "必须保留、禁止出现、透明或绿幕要求",
  "references": ["objectKey、资源 ID 或本地文件说明"]
}

Infer what is already clear and ask only for missing fields that block the selected endpoint. Reuse the current spec unless the user changes style, subject family, palette, format, or constraints. Store structured context under generationInputs.artSpec where supported and summarize it in the prompt when useful.

Intent Map

User intent	MCP tool and action
Find, open, create, or rename a canvas project	find_canvas_projects (list, recent, get); manage_canvas_projects (create, rename)
Read project resources or library records	find_assets (get_project_resources, list_library)
Create or change folders and asset records	organize_asset_library (create_folder, update_folder, create_asset, update_asset)
Upload a local image/audio/video asset	prepare_asset_upload (create_upload_ticket), client-side OSS form upload, then prepare_asset_upload (confirm_upload)
Register existing media in a project, read a canvas, or save its full layout	edit_canvas (register_resource, get, save_layout)
Generate a background, character, spec, UI mockup, or publication image	generate_image
Retouch an existing image, make a reference variation, or remove its background	modify_image (edit, variation, remove_background)
Build a transparent icon/game atlas from a registered visual spec	generate_icon_spritesheet
Generate marked assets from an existing UI design	extract_ui_assets
Animate a character into frames	generate_character_animation
Generate video	generate_video
Generate a sound effect or background music	generate_audio (sound_effect, background_music)
Check generation progress or retrieve its result	check_generation
Obtain temporary access to private media	find_assets (get_download_url)
Delete an exact project, folder, or asset record	delete_resources (delete_project, delete_folder, delete_asset)

For tools with actions, send { "action": "...", "input": { ... } }; place idempotencyKey at the top level when supported or required. Tools without actions accept operation fields directly, with idempotencyKey at the top level for generation. The direct operation tools use body, pathParameters, and queryParameters wrappers as shown by their live schemas.

Do not present an API menu unless the request is genuinely ambiguous. Ask a follow-up when two routes create different artifacts, for example “处理这张图” could mean edit, extract marked UI assets, or use it as a reference for a new generation.

Route-Specific Decisions

• Use modify_image edit when the requested output modifies a registered source image. Use variation when reference images should guide a new quick-edit image; it is image generation with fixed kind="quick-edit". Use remove_background for a static source image. With projectId, targetLayerId may replace a matching existing layer when no explicit canvasCompletion is supplied.
• Use icon spritesheet generation for a transparent reusable atlas when a stable visual-spec reference and concrete iconDescriptions exist. Do not use ordinary image generation just because it can draw several objects.
• Use UI extraction only for an existing UI design image with red-box annotations. It is not UI generation.
• Character animation requires a real sourceLayerId, source image, and dimensions from an existing resource. A local-only file must first be uploaded and registered where needed; do not invent a layer ID.
• For video with image/video/audio references, use a Seedance 2.0-family model; default to seedance2.0-fast, mode: "std", and explicit sound.
• prepare_asset_upload obtains a ticket and confirms an uploaded object; it does not transfer the file or register a project resource, asset record, or canvas layer. Use edit_canvas register_resource or organize_asset_library create_asset only when the task needs those records.
• Use temporary signed URLs only for preview/download. Feed stable objectKey or registered resource/asset identifiers into generation as each operation permits.

Example: Reusable Icon Assets

When the task needs a visual spec and a reusable icon atlas:

1. Reuse an existing registered icon-spec, or generate the requested spec using generate_image with kind=spec and register it as assetKind=icon-spec if necessary.
2. Call generate_icon_spritesheet with that registered ID as referenceId, concrete iconDescriptions, and explicit sliceMode. Choose grid only for requested equal cells or fixed slots and provide those gridX/gridY values; otherwise use connected-components, optionally with sliceCount.
3. Query check_generation and inspect the full sheet and actual slices. Preserve warnings; a usable full sheet does not imply that individual slices exist. Use returned slice identities and dimensions rather than guessing crop coordinates.

An ordinary UI mockup or uploaded image is not automatically an icon-spec. For extracting marked components from a UI design, use extract_ui_assets, which includes generation and does not promise pixel-exact cropping.

Scope Boundary

Stay within /api/external/v1. Do not invent worker, queue, runtime task-list, admin, profile, or SpacetimeDB calls. The only external generation query is GET /api/external/v1/generations/{operationId}. The hosted MCP also exposes the Skill and OpenAPI resources at genarrative://external-editor/skill, its four skill/references/*.md URIs, and genarrative://external-editor/openapi; keep those URI names unchanged.