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.

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 always uses summary; call get_editor_project 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.

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
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	sliceLayout, 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 nine 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 to write generated output into the canvas.
• Pass assetFolderId plus assetLabel for image, edit, icon spritesheet, video, sound effect, and BGM operations when supported.
• UI extraction uses assetFolderId and spritesheetLabel.
• Character animation accepts assetFolderId and assetLabel. Its completed compact result directly returns the final assetKind="character-animation" resource and asset with imageSequenceFrames and imageSequenceDurationMs; 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.

sliceLayout: "grid-2x2" is an opt-in contract for four fixed game-runtime assets. The provider prompt and server persistence both preserve the ordered slots left-top, right-top, left-bottom, right-bottom. Omit it to retain the default connected-component slicing behaviour for ordinary free-form icon sheets.

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.
• External v1 currently has no structured game-scene generation operation. Do not send kind: "scene" or assetKind: "scene" through generic image generation; the server rejects both before queueing.
• 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.