> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema-driven MCP attachments and results

> Declare MCP attachment paths, result formats, and media types in APIXO model schemas without adding model-specific client code.

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

1. Implement and verify the backend's public request and result behavior.
2. Add the schema, its paired model page, and the public index entry.
3. Declare the result format and every attachment path; use `attachments: []` when there are none.
4. Run the schema checks and client contract tests. The generator preserves the manual `mcp` object.
5. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.