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

API Operations

Use this reference after selecting a capability. Treat GET /api/external/v1/openapi.json as authoritative for exact request/response schemas, required fields, constraints, and operation IDs.

All paths below are relative to https://www.genarrative.world. Discovery and Skill download routes are public. Project, asset, upload, generation, and generation-query operations require the Bearer API Key.

MCP Tool to API Map

The hosted MCP offers the following tools. Choose the task tool when its action matches the request; the operation tool calls the indicated REST operation directly. Task tools with actions take { "action": "...", "input": { ... } }; tools without actions take the operation fields directly. idempotencyKey is top-level in task tools. Operation tools use body, pathParameters, and queryParameters wrappers from their live input schemas. Read the live tool schema and OpenAPI for exact required fields.

REST operation	Task tool (action)	Operation tool
GET /api/external/v1/openapi.json	—	get_external_open_api_json
GET /api/external/v1/editor/projects	find_canvas_projects (list)	list_editor_projects
GET /api/external/v1/editor/projects/recent	find_canvas_projects (recent)	load_recent_editor_project
GET /api/external/v1/editor/projects/{projectId}	find_canvas_projects (get), find_assets (get_project_resources), edit_canvas (get)	get_editor_project
POST /api/external/v1/editor/projects	manage_canvas_projects (create)	create_editor_project
PATCH /api/external/v1/editor/projects/{projectId}/metadata	manage_canvas_projects (rename)	rename_editor_project
DELETE /api/external/v1/editor/projects/{projectId}	delete_resources (delete_project)	delete_editor_project
PATCH /api/external/v1/editor/projects/{projectId}/canvas	edit_canvas (save_layout)	save_editor_project_canvas
POST /api/external/v1/editor/projects/{projectId}/resources	edit_canvas (register_resource)	create_editor_project_resource
POST /api/external/v1/assets/direct-upload-tickets	prepare_asset_upload (create_upload_ticket)	create_external_direct_upload_ticket
POST /api/external/v1/assets/objects/confirm	prepare_asset_upload (confirm_upload)	confirm_external_asset_object
GET /api/external/v1/assets/read-url	find_assets (get_download_url)	get_external_asset_read_url
GET /api/external/v1/editor/assets/library	find_assets (list_library)	get_editor_asset_library
POST /api/external/v1/editor/assets/folders	organize_asset_library (create_folder)	create_editor_asset_folder
PATCH /api/external/v1/editor/assets/folders/{folderId}	organize_asset_library (update_folder)	update_editor_asset_folder
DELETE /api/external/v1/editor/assets/folders/{folderId}	delete_resources (delete_folder)	delete_editor_asset_folder
POST /api/external/v1/editor/assets	organize_asset_library (create_asset)	create_editor_asset
PATCH /api/external/v1/editor/assets/{assetId}	organize_asset_library (update_asset)	update_editor_asset
DELETE /api/external/v1/editor/assets/{assetId}	delete_resources (delete_asset)	delete_editor_asset
POST /api/external/v1/editor/images/generations	generate_image, modify_image (variation, fixed kind="quick-edit")	generate_external_editor_image
POST /api/external/v1/editor/scenes/generations	structured game-scene generation (no hosted MCP tool yet)	generate_external_editor_scene
POST /api/external/v1/editor/images/edits	modify_image (edit)	edit_external_editor_image
POST /api/external/v1/editor/images/background-removals	modify_image (remove_background)	remove_external_editor_image_background
POST /api/external/v1/editor/icon-spritesheets/generations	generate_icon_spritesheet	generate_external_editor_icon_spritesheet
POST /api/external/v1/editor/ui-designs/assets/extractions	extract_ui_assets	extract_external_editor_ui_design_assets
POST /api/external/v1/editor/character-animations/generations	generate_character_animation	generate_external_editor_character_animation
POST /api/external/v1/editor/videos/generations	generate_video	generate_external_editor_video
POST /api/external/v1/editor/audios/sound-effects/generations	generate_audio (sound_effect)	generate_external_editor_sound_effect
POST /api/external/v1/editor/audios/background-music/generations	generate_audio (background_music)	generate_external_editor_background_music
GET /api/external/v1/generations/{operationId}	check_generation	get_external_editor_generation_job

The public agent-integration.json, skill/SKILL.md, and skill.zip routes and the MCP transport route are HTTP entry points, not callable MCP tools. The hosted resource URIs remain genarrative://external-editor/skill, genarrative://external-editor/skill/references/capability-routing.md, genarrative://external-editor/skill/references/api-operations.md, genarrative://external-editor/skill/references/authentication-and-safety.md, genarrative://external-editor/skill/references/requests-and-outputs.md, and genarrative://external-editor/openapi.

Project and Canvas Operations

Operation	Method and path	Minimum input
List projects	GET /api/external/v1/editor/projects	Authentication; optional view=full|summary (default full)
Create project	POST /api/external/v1/editor/projects	Optional title
Load recent project	GET /api/external/v1/editor/projects/recent	Authentication
Get project	GET /api/external/v1/editor/projects/{projectId}	projectId
Delete project	DELETE /api/external/v1/editor/projects/{projectId}	projectId
Rename project	PATCH /api/external/v1/editor/projects/{projectId}/metadata	title
Save canvas	PATCH /api/external/v1/editor/projects/{projectId}/canvas	viewport, layers, expectedRevision
Add project resource	POST /api/external/v1/editor/projects/{projectId}/resources	imageSrc, width, height, sourceType

Canvas save uses optimistic revision control. Pass the last authoritative expectedRevision; on conflict, reload instead of replaying a stale full layout.

Project listing supports two views:

• view=full is the REST default and returns the complete project, canvas, layers, and resources.
• view=summary returns only projectId, title, updatedAt, and nullable cover, so callers can display, search, disambiguate same-name projects, and select a safe target without loading every canvas snapshot.
• Hosted MCP list_editor_projects and find_canvas_projects (list) use summary; call get_editor_project or find_canvas_projects (get) after selecting a projectId when complete authoritative state is required.
• cover contains only resourceId, stable objectKey, dimensions, and updatedAt. It never embeds image bytes, a Data URL, or a signed URL. To display it, pass cover.objectKey to get_external_asset_read_url; signed URLs are temporary and must not be persisted or reused as generation references.

Asset and Upload Operations

Operation	Method and path	Minimum input
Create direct-upload ticket	POST /api/external/v1/assets/direct-upload-tickets	legacyPrefix, fileName
Confirm uploaded object	POST /api/external/v1/assets/objects/confirm	objectKey, assetKind
Get signed read URL	GET /api/external/v1/assets/read-url	objectKey or legacyPublicPath
Read asset library	GET /api/external/v1/editor/assets/library	Authentication
Create folder	POST /api/external/v1/editor/assets/folders	label
Update folder	PATCH /api/external/v1/editor/assets/folders/{folderId}	label or collapsed
Delete folder	DELETE /api/external/v1/editor/assets/folders/{folderId}	folderId
Create asset record	POST /api/external/v1/editor/assets	folderId, label, imageSrc, width, height, sourceType
Update asset record	PATCH /api/external/v1/editor/assets/{assetId}	label or folderId
Delete asset record	DELETE /api/external/v1/editor/assets/{assetId}	assetId

Upload is a three-step client flow: create a ticket, POST the file and returned fields directly to the OSS form endpoint, then confirm the returned objectKey. See authentication-and-safety.md before implementing this flow. prepare_asset_upload handles the ticket and confirmation as separate calls; it does not send local bytes to OSS or automatically register a project resource, asset record, or canvas layer. manage_canvas_projects (create) likewise does not create a same-name asset folder. Register or organize records only when the task needs them.

Generation Operations

Every generation row requires a stable Idempotency-Key header and returns HTTP 202 with an asynchronous submission, not the generated media.

Capability	POST path	Required body fields	Common optional body fields
Image generation	/api/external/v1/editor/images/generations	prompt	kind, style, model, aspectRatio, imageSize, size, referenceImageSrcs, projectId, assetFolderId, assetLabel, canvasCompletion, generationInputs
Game scene	/api/external/v1/editor/scenes/generations	sceneContent, stylePreset	customStyle (required when stylePreset="custom"), model, aspectRatio, imageSize, referenceImageSrcs, projectId, assetFolderId, assetLabel, canvasCompletion, generationInputs
Image edit/redraw	/api/external/v1/editor/images/edits	prompt, sourceReferenceId	referenceImageSrcs, model, size, projectId, assetFolderId, assetLabel, targetLayerId, canvasCompletion
Background removal	/api/external/v1/editor/images/background-removals	sourceImageSrc	projectId, sourceResourceId, targetLayerId, static-image assetKind, assetFolderId, assetLabel, canvasCompletion, generationInputs
Icon spritesheet	/api/external/v1/editor/icon-spritesheets/generations	referenceId, iconDescriptions, sliceMode	gridX, gridY, sliceCount, style, referenceImageSrcs, screenColor, model, aspectRatio, imageSize, projectId, assetFolderId, assetLabel, canvasCompletion
UI asset extraction	/api/external/v1/editor/ui-designs/assets/extractions	sourceImageSrc, aspectRatio, imageSize	screenColor, model, referenceImageSrcs, projectId, assetFolderId, spritesheetLabel, canvasCompletion
Character animation	/api/external/v1/editor/character-animations/generations	sourceLayerId, sourceImageSrc, sourceWidth, sourceHeight, promptText, resolution, ratio, frameCount, durationSeconds, model	projectId, sourceResourceId, assetFolderId, assetLabel, canvasCompletion
Video generation	/api/external/v1/editor/videos/generations	prompt, model, aspectRatio, durationSeconds, resolution, mode, sound	referenceImageSrcs, referenceVideoSrcs, referenceAudioSrcs, webSearchEnabled, projectId, assetFolderId, assetLabel, canvasCompletion
Sound effect	/api/external/v1/editor/audios/sound-effects/generations	prompt	model, duration, loop, projectId, assetFolderId, assetLabel, canvasCompletion, generationInputs
Background music	/api/external/v1/editor/audios/background-music/generations	gptDescriptionPrompt, makeInstrumental	projectId, assetFolderId, assetLabel, canvasCompletion, generationInputs

Poll all ten through:

GET /api/external/v1/generations/{operationId}

Supply the operationId returned by submission. Poll no faster than pollAfterMs and retain the ID after a caller-side timeout.

Canvas and Library Field Rules

• Pass projectId and canvasCompletion when the task calls for generated output in a canvas.
• Pass assetFolderId plus the relevant label field when the task calls for a library record. Neither destination requires the other, and their names need not match.
• UI extraction uses assetFolderId and spritesheetLabel.
• Character animation accepts assetFolderId and assetLabel and persists the generated sequence. Consume returned artifacts and persisted identities; never create a duplicate first-frame resource or asset.
• Background removal derives the final static-image assetKind from the authoritative source record. A conflicting request kind or any video, audio, animation, or image-sequence kind returns 400 before queueing. Without canvasCompletion, targetLayerId must point to the same authoritative object as sourceImageSrc (prefer assetObjectId, otherwise canonical bucket/object key).
• If a caller must manually create a character-animation resource or asset, put the authoritative frames and total sequence duration in imageSequenceFrames and imageSequenceDurationMs. Keep generationInputs replayable: it must not contain legacy runtime fields such as characterAnimation, frames, previewVideoPath, frameCount, fps, or durationSeconds.
• Reload project/library state after completion when full current state is required.

Reference Field Mapping

After confirming a local upload, pass its stable objectKey into operations that accept object references:

Target capability	Field
Image generation	referenceImageSrcs
Image edit/redraw	sourceReferenceId must be a registered project resource ID or asset ID; additional references remain in referenceImageSrcs
Icon spritesheet	Register the primary spec as an assetKind="icon-spec" project resource or asset, then pass its returned ID as referenceId; additional style references remain in referenceImageSrcs
UI design extraction	sourceImageSrc; additional references in referenceImageSrcs
Character animation	sourceImageSrc
Video with image references	referenceImageSrcs

For image edit/redraw, confirming an upload is not sufficient: create a project resource or asset-library record first, then pass that record's ID as sourceReferenceId. The main source never accepts objectKey, URL, Data URL, or Blob URL. Use video/audio reference arrays only with models that support them. Do not pass an expiring signed read URL as a generation reference.

The icon-spritesheet primary referenceId is intentionally stricter than ordinary image references: it accepts only a current-owner project resource ID or asset ID whose authoritative assetKind is icon-spec. It does not accept an objectKey, URL, Data URL, or Blob URL.

sliceMode is required and has no default, so every request must state it. Use "connected-components" to detect independent opaque regions by alpha connectivity, or "grid" with positive gridX and gridY values (maximum 32 each) only when the requirement names equal grid cells or fixed slots; the dimensions must come from that requirement. connected-components must not carry gridX/gridY, and sliceCount constrains the connected-component result instead of expressing a grid. Omitting sliceMode, or contradicting the declared mode with grid dimensions, returns 400 before pricing, enqueueing, or any provider call.

Common Values

Use OpenAPI as the final authority; these common values are a routing aid:

• Image kind: spec, character, quick-edit, ui-design, publication-material; ordinary image generation may omit it.
• Game scenes must use the dedicated structured route POST /api/external/v1/editor/scenes/generations (sceneContent + stylePreset; customStyle required for custom). Do not send kind: "scene" or assetKind: "scene" through generic image generation; the server rejects both before queueing. The scene route assembles the full provider prompt server-side and never accepts a caller-assembled prompt.
• Image model: gpt-image-2, gemini-3.1-flash-image-preview, nanobanana2, nano-banana.
• Image aspectRatio: 1:1, 2:3, 3:2, 9:16, 16:9.
• Image imageSize: 0.5K, 1K, 2K.
• Video model: seedance2.0, seedance2.0-fast, kling3.0, kling3.0-omni, veo3.1, veo3.1-fast.
• Video aspectRatio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9.
• Video resolution: 480p, 720p, 1080p; mode: std; sound: on or off.
• Character animation uses model: "seedance2.0-fast"; resolution: 480p or 720p; frameCount: 32, 40, or 48; durationSeconds: 4, 5, or 6; ratio: same, 1:1, 4:3, 16:9, 9:16, or 3:4.
• Sound effect uses canonical model eleven_text_to_sound_v2; omit duration or send null for automatic duration, otherwise send a finite 0.5-30 number. loop defaults to false and remains independent from Prompt text.
• UI extraction uses aspectRatio: "1:1"; use imageSize: "1K" for normal/small extraction and 2K for dense designs.

Do not hard-code this list as a replacement client schema. In particular, the top-level image style field is intentionally extensible; see requests-and-outputs.md for its fallback behavior.