Schema-driven MCP attachments and results

Public task model schemas include a top-level mcp object. It describes how a client binds uploaded files and reads task results. It does not change request authentication, API endpoints, Studio sessions, billing, or backend parameter validation.

Contract version 1.0

{
  "mcp": {
    "version": "1.0",
    "result": { "media_type": "video", "result_codec": "url_array_v1" },
    "attachments": [
      { "field": "image_urls", "media_type": "image", "shape": "string[]", "ordered": true },
      { "field": "elements[].image_urls", "media_type": "image", "shape": "string[]", "ordered": true }
    ]
  }
}

Default models and creation tools

The public model index declares shortcut defaults separately from model parameter schemas:

{
  "mcp": {
    "version": "1.0",
    "defaults": {
      "generate_image": "seedream-5-0-pro",
      "generate_video": "seedance-2-5",
      "generate_music": "suno",
      "generate_speech": "minimax-speech-2-8",
      "clone_voice": "cosyvoice-3-5-plus",
      "design_voice": "cosyvoice-3-5-plus"
    }
  }
}

Each value must be an exact canonical task model ID in that index. These are the current configured choices, not plugin constants. list_models.defaults returns {tool, model} references; the same model may serve several tools. Changing a default takes effect after the index cache refreshes. Missing bindings or unavailable documentation never trigger a built-in fallback or automatic model switch. All seven creation tools use the same arguments: input, optional reference_files/file_bindings, and Studio session references. generate_task requires model; the six shortcuts may omit it to use the index default, or specify another task model. Read that model’s complete schema before constructing input. The tool name chooses the default and keeps its own authorization/rate-limit identity; it does not inject a mode or rewrite model fields. Use the mode for the requested operation from the selected schema, including speech, cloning or design.

{
  "session_title": "A garden",
  "input": { "mode": "text-to-image", "prompt": "A quiet garden" }
}

This is an example generate_image call. Model parameters such as prompt, mode, voice, voice_id, and customMode go inside input, using the selected schema’s original names and values. Legacy flat arguments, reference_images, and reference_audio are not accepted. No model defaults, inferred languages, preset voices or field aliases are added. Model semantics are validated by the backend; transport, credentials, sessions, attachment safety and bounded result parsing remain enforced by the client.

Attachment paths

Each binding declares a parameter path, media hint (image, video, audio, mixed, or file), and URL shape (string or string[]). The field must exist in the input schema; nested paths must start at an object or object array. Paths use named object keys and [] for array items, with at most 16 segments. No executable expressions, arbitrary object traversal, transport fields or prototype keys are supported. For elements[].image_urls, send input.elements=[{"name":"hero"}] and file_bindings=[{"field":"elements[0].image_urls","file_indices":[1,0]}]. The named item must already exist. Only the missing URL leaf is filled; names, timestamps and other metadata stay unchanged. Each file is used once, explicit order is preserved, and existing URL values cannot be overwritten. Direct media URLs and file bindings are separate input methods and are not mixed within one call. The client checks attachment URL safety without downloading media. The backend validates media content and model-specific limits.

Result formats

result_codec	media_type	Public result contract
`url_array_v1`	image, video, audio, speech	`resultJson.resultUrls` or top-level `resultUrls`, a nonempty array of public HTTP(S) URLs
`suno_tracks_v1`	music	`resultUrls` contains track objects with `audio_url` and optional `image_url`
`text_outputs_v1`	text	`resultJson.outputs` is a nonempty array of plain text strings
`cosyvoice_v1`	audio	Speech URL results or ready voice results with `voice_id` and `voice_status=OK`; `UNDEPLOYED` is not usable
`minimax_voice_v1`	voice	Successful reusable voice with `voice_id` and `voice_type=active`; preview URLs may be absent

These versioned names identify formats, not model eligibility lists. Any model can declare the matching format after its observable results are verified. Decoders enforce bounded output and URL safety; unknown raw fields never become user-facing results. A new output shape needs a decoder, not an arbitrary extraction expression in schema. For cosyvoice_v1, also declare mode_media_types, mapping documented lowercase mode values to speech or voice, for example {"speech":"speech","clone":"voice","design":"voice"}. Clients match trimmed, case-insensitive mode spellings for the creation result hint without rewriting input. Carry that hint when polling; task IDs and file extensions do not identify the operation. Voice lifecycle fields remain authoritative, and a voice ID is reusable only after successful readiness.

Adding or updating a model

Implement and verify the backend’s public request and result behavior.
Add the schema, its paired model page, and the public index entry.
Declare the result format and every attachment path; use attachments: [] when there are none.
Run the schema checks and client contract tests. The generator preserves the manual mcp object.
Publish through the normal release process. Clients read the public schema after their cache refreshes.

Missing, malformed, or unsupported declarations do not hide the schema. Clients show the complete document. Task creation requires valid attachment and result declarations; querying an existing task only requires a valid result declaration. An invalid attachment declaration does not disable result decoding. All task creation and queries load the selected schema, including default shortcuts. Schema declarations cannot override credentials, request URLs, session references, or security checks. LLM gateway schemas use their own API protocols and do not declare this task contract.

​Contract version 1.0

​Default models and creation tools

​Attachment paths

​Result formats

​Adding or updating a model

Contract version 1.0

Default models and creation tools

Attachment paths

Result formats

Adding or updating a model