---
title: "Generate Asset"
method: POST
path: "/api/mcp/generate_asset"
tags: ["mcp"]
---

# Generate Asset

`POST /api/mcp/generate_asset`

## Request

- Base URL: `https://writer.swapp1990.org` (the document declares no server; this is the origin it was published from)
- URL: `https://writer.swapp1990.org/api/mcp/generate_asset`
- Auth: none declared

Start an async Writer visual-asset generation through DesignForYou.

Normalizes a structured `asset-generation/v1` brief, then kicks off a
background job that asks DesignForYou to recommend a template and
calls its `/api/mcp/generate` tool. Returns immediately with
`{job_id, status: "running"}` — poll `get_asset_status` until the job
is terminal. The expert image-edit path can take well over two
minutes, so this never blocks the HTTP request. Pass
`generation.session_id` to refine a previous result, and
`generation.context_ids` to use prior DesignForYou designs as visual
references.

## Request body

- GenerateAssetInput
  - `request_id` string, nullable: Optional idempotency/correlation id. Writer creates one if omitted.
  - `asset_kind` string: cover, poster, icon, social_post, screenshot, character, background, diagram, or other.
  - `use_case` string, required: Short natural-language summary of why the asset is needed.
  - `audience` string, nullable: Optional target audience.
  - `platform` string, nullable: Optional publishing target.
  - `format` AssetFormatInput
    - `aspect_ratio` string, nullable: Target aspect ratio, such as 2:3, 1:1, or 16:9.
    - `width` integer, nullable: Optional target width in pixels.
    - `height` integer, nullable: Optional target height in pixels.
    - `transparent_background` boolean: Whether the asset should use a transparent background.
  - `content` AssetContentInput, required
    - `primary_text` string, nullable: Required title, headline, or text to include.
    - `secondary_text` string, nullable: Optional supporting text.
    - `brand_or_creator` string, nullable: Optional creator name, imprint, or brand.
    - `description` string, required: What the asset should depict.
  - `visual_direction` AssetVisualDirectionInput
    - `genre_or_category` string, nullable: Optional category, genre, or shelf signal.
    - `style` string, nullable: Visual style direction.
    - `mood` string, nullable: Tone or emotional feel.
    - `palette` string, nullable: Palette hint.
    - `motifs` string[]: Recurring visual motifs to consider.
  - `constraints` AssetConstraintsInput
    - `required` string[]: Elements that must appear.
    - `avoid` string[]: Elements that should not appear.
    - `forbidden_text` string[]: Placeholder or banned words to avoid.
    - `safe_zone` string, nullable: Safe-zone or crop guidance.
  - `generation` AssetGenerationOptionsInput
    - `variant_count` integer: Number of variants to request.
    - `variants` string[]: Optional explicit variant labels.
    - `template_id` string, nullable: Optional pinned DesignForYou template id.
    - `template_category` string, nullable: Optional category filter for recommendation.
    - `template_subcategory` string, nullable: Optional subcategory filter for recommendation.
    - `quality` string: Requested quality tier: fast, standard, or high.
    - `context_ids` string[]: Prior DesignForYou design ids for visual context.
    - `context_labels` string[]: Optional human labels for each context_id, in the SAME order. When the edit routes to a multi-reference model (gpt-image-2), DesignForYou appends an ordered legend ('reference 1 = <label>, ...') so the model binds each named subject to its own reference image instead of blending identities.
    - `skip_prompt_merge` boolean: Skip DesignForYou's smart prompt-merge (which compresses to ~150 words) and send the description verbatim. Set for prompts that are already complete and precise — e.g. a multi-character cover where each subject's outfit + reference legend must survive.
    - `scene_prompt_final` boolean: Scene-stills only: content.description is already the planned, user-editable shot prompt and should be sent through without running the scene prompt planner again.
    - `client_prompt_final` boolean: Scene-stills only: the prompt was supplied directly by the client and must be passed to the local provider verbatim without adding a server style preamble.
    - `prompt_passthrough` boolean: Internal Writer flag for an already-final prompt. When true, preserve the description without planner rewriting or whitespace normalization before the downstream call.
    - `session_id` string, nullable: Prior DesignForYou session id to refine.
    - `edit_tier` string, nullable: Edit tier: fast, pro, or expert (expert routes refs to gpt-image-2 edit).
    - `model` string, nullable: Optional DesignForYou image model override, such as grok-imagine-image-quality, gpt-image-2, minimax-h3-image-balanced, or minimax-h3-image-quality.
    - `provider` 'grok_cli' | 'minimax_h3', nullable: Explicit image provider. 'grok_cli' runs the signed-in local Grok Build CLI and returns a durable S3 URL plus a local data URL for paragraph scene stills and single paragraph images; 'minimax_h3' is forwarded to DesignForYou's hosted MiniMax H3 image model for scene stills. Hosted DesignForYou remains the default.
    - `reference_urls` string[]: Resolved visual reference image URLs for local providers. Writer can populate this from saved character-sheet and location references or accept client-supplied references directly.
    - `reference_labels` string[]: Optional ordered labels aligned with reference_urls for local Grok CLI binding. Internal generation metadata; optional/defaulted for compatibility.
    - `reference_roles` string[]: Optional ordered roles aligned with reference_urls: identity, style, location, or composition. Internal generation metadata; optional/defaulted for compatibility.
    - `reference_sources` string[]: Optional ordered sources aligned with reference_urls (client, cast, location). Internal generation metadata for diagnostics.
    - `reference_warnings` string[]: Optional diagnostic warnings collected while sanitizing references (e.g. duplicate URLs).
    - `style_lock` string, nullable: Optional rendering style lock text forwarded to the local Grok paragraph-image path.
    - `style_lock_mode` 'auto' | 'client' | 'none', nullable: How style_lock was chosen: auto (Writer default), client (supplied), or none (disabled).
    - `frame_mode` string, nullable: Optional local-provider frame contract, e.g. single_full_bleed for paragraph images.
    - `reference_subject_free` boolean[]: Optional ordered flags aligned with reference_urls. A true value declares that a style reference contains no people or character subjects.
  - `metadata` AssetMetadataInput
    - `downstream_user` string, nullable: Optional already-opaque downstream user id.
    - `downstream_project` string, nullable: Optional downstream project/story id; Writer hashes it before sending.

## Response `200`

Successful Response

- GenericToolResponse: Fallback for tools whose payload is still being tightened.
  - `story_url` string, nullable
  - `article_url` string, nullable
  - `job_id` string, nullable
  - `status` string, nullable
  - `is_terminal` boolean, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api.md) · [All operations](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/revisions/ce5e2a89ab4d?raw)