Genarrative/.codex/skills/genarrative-external-editor-api/SKILL.md

name, description

name

description

genarrative-external-editor-api

Guide use of Genarrative's hosted external editor/canvas MCP or asynchronous `/api/external/v1` OpenAPI. Use when an Agent needs to discover the hosted integration, choose a canvas or asset operation, upload local reference media, create or update projects and asset-library records, submit and poll image/video/audio generation, interpret generated artifacts and warnings, draft HTTP/Python calls, or securely handle a Genarrative developer API Key.

Genarrative External Editor API

Discover the live integration through GET https://www.genarrative.world/api/external/v1/agent-integration.json. Treat GET https://www.genarrative.world/api/external/v1/openapi.json as the field-level source of truth. In this repository, the same contract is docs/openapi/genarrative-external-v1.openapi.json.

Prefer the hosted Streamable HTTP MCP at https://www.genarrative.world/api/external/v1/mcp when the Agent supports remote MCP with a custom Bearer token. It exposes the External v1 operations as tools and the Skill documentation as resources; it does not require a local MCP server. Use this complete Skill package when remote MCP is unavailable or local-file upload needs client-side orchestration.

Prefer scripts/genarrative_external_api.py for runnable REST calls. It uses only Python stdlib, reads the local private API Key file, keeps the production base URL fixed, uploads local references, and wraps asynchronous submission, polling, and result retrieval.

Workflow

1. Discover the integration manifest. Choose hosted MCP when supported; otherwise use the helper or direct REST.
2. Before the first generation in a new conversation, obtain a canvas name unless an existing projectId and assetFolderId were supplied. Create or reuse a project and a same-name asset-library folder. Retain canvasName, projectId, assetFolderId, and the current art spec.
3. Normalize art requests into a reusable spec. Ask only for missing values that block the selected operation. Reuse the spec until the user changes its style, subject family, palette, format, or constraints.
4. Infer the operation from the user's intent. Do not ask the user to select an API unless two operations would produce materially different artifacts.
5. If a reference exists only as a local file, upload and confirm it first. Pass the stable returned objectKey to operations that accept object references; never substitute a temporary signed URL. For an icon-spritesheet primary spec, additionally create a project resource or asset record with assetKind="icon-spec", then pass the returned resource or asset ID as referenceId.
6. For generation endpoints that support the fields, include projectId, assetFolderId, an asset label, and canvasCompletion so the result enters both the canvas and its same-name library folder.
7. Treat every generation POST as asynchronous. Send one stable Idempotency-Key per logical request, retain the returned operationId, and poll the returned statusUrl or GET /api/external/v1/generations/{operationId} according to pollAfterMs.
8. Consume result only after status=completed. On failed, surface the safe error. On a client timeout or lost response, retain the operation/key; do not create a replacement request.
9. Reload the normal project or asset-library read endpoint when the caller needs complete authoritative state. Generation results are intentionally compact.
10. Stay within /api/external/v1. Never call internal workers, queues, admin/profile APIs, or SpacetimeDB endpoints unless the user explicitly changes scope.

Essential Invariants

• Authenticate MCP and business API calls with Authorization: Bearer <tnr_sk_...>. Never ask the user to paste a key into chat or place one in repository files.
• All nine generation POST routes require Idempotency-Key and return HTTP 202; 202 is durable acceptance, not a media result.
• Retry an uncertain submission only with the exact same body and the same idempotency key. A polling timeout is not permission to generate again.
• Use stable references such as objectKey, project resource ID, or asset ID where each operation permits them. Image edit/redraw is stricter: sourceReferenceId accepts only a registered project resource ID or asset ID; upload confirmation alone is not enough. Use /assets/read-url only for temporary preview/download access.
• Preserve both warning channels after completion. A general warning can coexist with sliceWarning; do not discard either.
• Do not invent missing derivatives. A source-preserved warning means the main source remains usable but requested post-processing failed. A slice warning means the complete transparent sheet is usable but individual slices are absent.
• Icon spritesheet generation requires an explicit sliceMode and has no default. Use sliceMode="grid" with the gridX and gridY the requirement actually names (1-32 each) only for equal grid cells or fixed slots; use sliceMode="connected-components" for free-form sheets or an open number of subjects, and constrain the count with sliceCount instead of inventing grid dimensions. connected-components must not carry gridX/gridY; an omitted, contradictory, or misapplied declaration returns 400 before billing.
• For successful style="pixelArt", treat completed-result and nested resource/asset dimensions as the final logical-grid PNG dimensions. They may differ from size, imageSize, the provider image, and canvasCompletion.placeholder; do not rescale or reject the artifact to match those inputs.
• Keep generated artifacts in the canvas and asset library together. Character animation accepts assetFolderId and assetLabel; its completed result directly returns the final assetKind="character-animation" resource and asset with formal sequence fields. Do not create a duplicate first-frame record.

Documentation Navigation

Read only the references needed for the task, but always verify exact schemas and enums against live OpenAPI:

• references/capability-routing.md: read before selecting an MCP tool or REST operation, creating a canvas session, or working in the AI game creator visual DAG.
• references/api-operations.md: read when constructing project, canvas, asset-library, upload, generation, or generation-status calls.
• references/authentication-and-safety.md: read before handling credentials, local files, OSS form upload, retries, private media, or logs.
• references/requests-and-outputs.md: read before building generation payloads, polling, interpreting compact results, applying canvas completion, or handling post-processing warnings.

The hosted MCP exposes the same documents through:

• 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
• genarrative://external-editor/openapi

Hosted Integration Discovery

• Manifest: GET /api/external/v1/agent-integration.json.
• Hosted MCP: POST /api/external/v1/mcp, Streamable HTTP, same Bearer API Key.
• OpenAPI: GET /api/external/v1/openapi.json.
• Raw Skill entry: GET /api/external/v1/skill/SKILL.md.
• Complete Skill archive: GET /api/external/v1/skill.zip.

The archive contains this main file, four one-level references, the Python helper, and agents/openai.yaml. Verify its SHA-256 against agent-integration.json before installing. Discovery, OpenAPI, and Skill downloads are public; MCP and business operations require authentication.

Python Helper

Store the API Key outside the repository at ~/.config/genarrative/external-editor-api.json:

{
  "apiKey": "tnr_sk_..."
}

Set restrictive permissions where possible, then smoke-test without printing the key:

chmod 600 ~/.config/genarrative/external-editor-api.json
python3 .codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py list-projects

For a canvas-backed generation:

from genarrative_external_api import GenarrativeExternalClient

client = GenarrativeExternalClient()
session = client.prepare_canvas_session("新画板")
client.generate_image(
    "生成一张 16:9 幻想森林游戏背景",
    canvasSession=session,
    assetLabel="森林背景",
    aspectRatio="16:9",
    imageSize="1K",
    artSpec={
        "assetType": "background",
        "subject": "幻想森林主视觉",
        "style": "手绘游戏概念图",
        "palette": "翡翠绿与金色光斑",
        "composition": "横版，中心留出角色站位",
        "format": "16:9, 1K",
        "constraints": "无文字、无 UI 按钮",
        "references": [],
    },
)

For background removal, pass a stable owner-scoped object key, project resource ID, or asset ID; the helper keeps the same asynchronous submission and polling contract:

session = client.prepare_canvas_session("去背景画布")
client.remove_background(
    "editor-upload/object.png",
    source_width=720,
    source_height=1280,
    canvasSession=session,
    assetLabel="去背景结果",
)

Background removal preserves the source pixel size. For normal canvas placement with canvasSession, pass the real source_width and source_height, or provide both canvasWidth and canvasHeight; the helper rejects missing dimensions instead of guessing a square placeholder. assetKind may only describe a static image and must match the authoritative source record. Prefer a project resource ID or asset ID when the same object key has multiple semantic registrations; for a raw object key outside in-place replacement, pass sourceResourceId to disambiguate. Passing targetLayerId selects in-place replacement: the helper retains the session's project/library context but does not inject canvasCompletion, and it rejects an explicit canvasCompletion combined with targetLayerId. The target layer must point to the same authoritative object as the source, and the server durably binds a raw object key to that target resource for Worker revalidation.

Helper convenience methods wait locally, but the server still uses short asynchronous submit/status requests. For durable caller-controlled orchestration, call submit_generation, persist its operationId and idempotency key, then call get_generation or wait_for_generation.

For character animation, pass the canvas session and asset label to animate_character. The helper submits asynchronously and returns the completed compact result containing the authoritative formal resource and asset; do not synthesize a library asset from the first frame.

Guardrails

• Do not change the fixed production base URL in generated examples.
• Do not move the API Key into environment variables, source files, generated projects, logs, docs, screenshots, or shell snippets containing literal secrets.
• Do not treat a Data URL, Blob URL, expiring signed URL, worker lease, or provider diagnostic as a durable result.
• Do not reconstruct authoritative canvas, resource, or library snapshots from a compact generation response.
• Do not replace icon-spritesheet generation with ordinary image generation when the deliverable requires a reusable transparent atlas.