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

# Generation tools

> MCP image, video, editing, cloning, avatar, and result contracts.

Generation tools submit asynchronous work and return a
[task receipt](#results-and-errors). They consume credits and may trigger configured
automatic reload. Submit once and follow the returned task.

<Warning>
  A receipt confirms a submission outcome; it does not prove completed media.
  On `GENERATION_SUBMISSION_UNCONFIRMED`, do not automatically resubmit. Check
  generation history first, including when receipt retrieval failed after
  creation.
</Warning>

## Common inputs

Use the current `tools/list` schema and
[account-specific defaults](/mcp/tools#account-specific-defaults).
The references below mark required creative inputs; defaulted settings may be
omitted.

| Input | Contract |
| - | - |
| Media ID | A positive signed 64-bit decimal string for your own non-deleted media of the required file type. |
| Uploaded source | An object containing only `url`, using the canonical value returned by your own `import_file` or `complete_file_upload`. See [Uploads](/mcp/uploads-and-live). |
| Source pair | Supply exactly one media-ID source or uploaded source. Supply at most one form of each optional end/reference source. |
| `modelId` | An accessible model appropriate to the operation. For `create_image`, I2V, and T2V, omission or `null` selects generation without a character model. Other tools reject explicit `null`. |
| `elementIds` | Where supported, an ordered array of distinct accessible positive decimal ID strings. Omit or use `[]` for none. Bind every prompt `<element\|ID>` reference in this array. |
| `width`, `height` | Where supported, paired aspect-ratio components: `(9,16)`, `(3,4)`, `(1,1)`, `(4,3)`, `(16,9)`. They are not pixel dimensions. |
| Duration | I2V, T2V, and extension durations are integers in milliseconds, in whole-second increments. |

Do not substitute a signed `previewUrl` or an arbitrary external URL for an
uploaded source. Dimensions and duration are resolved by the server. Optional
settings must satisfy the chosen quality's limits even when other values are
defaulted.

## Image prompt resource

Before constructing a `create_image` prompt, read
`apob://docs/image-prompt-format/v1` with `resources/read`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "resources/read",
  "params": { "uri": "apob://docs/image-prompt-format/v1" }
}
```

Wrap prose in nonblank `<text|...>` segments. When selecting a character model,
include the exact `<personindicator|[[apob]]>` marker outside text segments. Without
a model, omit that marker. Element markers must also remain outside text and
refer to IDs bound in `elementIds`. Only whitespace may appear between segments;
nested tags, literal angle brackets inside text, and unsupported tags are rejected.

Plain-language editing and video prompts use their own workflow contracts;
they do not require the `create_image` prose tags.

## Image tools

### create\_image

Required: `prompt` in the resource format. Optional: `modelId`, `outputQuality`,
`width`, `height`, `numSamples`, `elementIds`.

Qualities are `ultraFast`, `ultra`, `ultra4k`, `ultraS`. `numSamples` defaults to
`2`; it must be `1–4` for `ultraFast`/`ultra`, or `1–2` for `ultra4k`/`ultraS`.
Image elements must contain image resources; the first image is used.

| Quality | Maximum image elements without a model | Maximum with a selected model |
| - | - | - |
| `ultraFast` | 1 | 1 |
| `ultra` | 9 | 8 |
| `ultra4k` | 14 | 13 |
| `ultraS` | 10 | 9 |

This call requests one no-model image with explicit settings:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "create_image",
    "arguments": {
      "prompt": "<text|A quiet mountain lake at sunrise, soft mist>",
      "outputQuality": "ultra",
      "width": 16,
      "height": 9,
      "numSamples": 1
    }
  }
}
```

### create\_portrait\_master

Creates one `2048 × 2048` character image. It returns a generation receipt;
creating a reusable character model is a separate [`create_model`](/mcp/library-and-elements#character-models)
operation.

`subType` is `human` (default) or `nonHuman`. `prompt` is optional for humans and
required for `nonHuman`, with a maximum of 4096 characters.

Human-only optional inputs are `gender`, `build`, `nationality1`, `nationality2`,
`eyesColor`, `faceShape`, `hairStyle`, `hairColor`, and `shot` (each nonblank, up to
256 characters); `age` (`0–150`); `humanWeight` (positive integer grams);
`humanHeight` (positive integer millimeters); and boolean `dimple`, `beard`,
`tanned`. Weight and height must fit a signed 32-bit integer.

Only `nonHuman` accepts one optional `referenceImageMediaId` or
`uploadedReferenceImage`. Human attributes cannot be supplied for `nonHuman`.
This tool exposes no quality, sample-count, or ratio arguments.

### edit\_image

Required: a plain nonblank `prompt` and exactly one `sourceMediaId` or
`uploadedImage`. Optional: `outputQuality`, paired `width`/`height`, `elementIds`,
and one `referenceImageMediaId` or `uploadedReferenceImage`.

Qualities are `ultra` (default), `ultra4k`, `ultraS`. Omitted dimensions preserve
the source ratio. The image budget includes source and separate reference:
14 total for `ultra`/`ultra4k`, 10 for `ultraS`. `modelId` is not accepted.

### clone\_image

Required: exactly one `sourceMediaId` or `uploadedImage`, plus an accessible
portrait `modelId` or separate identity image (`referenceImageMediaId` or
`uploadedReferenceImage`). Optional: `prompt` (nonblank, up to 4096 characters),
`outputQuality`, paired `width`/`height`, `preserveOptions`, `elementIds`.

Qualities are `ultra`, `ultra4k`, `ultraS` (default). `preserveOptions` is a unique
array of `outfit`, `pose`, `background`; omission preserves all three. Omitted
dimensions preserve the source ratio. Two image slots are reserved for source
and identity, leaving at most 12 image elements for `ultra`/`ultra4k` or 8 for
`ultraS`.

## Video generation and extension

### create\_image\_to\_video

Required: plain nonblank `prompt` and exactly one `sourceMediaId` or
`uploadedImage`. Optional: `modelId`, `outputQuality`, `durationMs`, `resolution`,
`enableBgm`, `elementIds`, and one `endImageMediaId` or `uploadedEndImage`.

### create\_text\_to\_video

Required: plain nonblank `prompt`. Optional: `modelId`, `outputQuality`,
`durationMs`, `resolution`, `enableBgm`, paired `width`/`height`, `elementIds`.
`best` requires an accessible character model; `high`, `ultra`, and `ultraS`
support no-model generation.

The following duration bounds apply to these two tools:

| Quality | I2V `durationMs` | T2V `durationMs` |
| - | - | - |
| `high` | 1000–15000 | 1000–15000 |
| `best` | 4000–10000 | 4000–10000 at `HD`; 1000–15000 at `FHD`/`QHD` |
| `ultra` | 2000–30000 | 2000–30000 |
| `ultraS` | 2000–30000 | 4000–30000 |

Resolutions are `SD`, `HD`, `FHD`, `QHD`, `UHD`. `SD` requires `high`; `UHD`
requires `ultra` or `ultraS`. `enableBgm` is a boolean requesting generated
audio/background sound and defaults to `true`.

These MCP tools do not accept `voiceScript`, `voiceModelId`, or `voiceModelIds`.
Place ordinary dialogue in `prompt` using the workflow's voice-section syntax;
voice-model selections are available on workflows that explicitly expose them.

### extend\_video

Required: exactly one `sourceMediaId` or `uploadedVideo`. Optional: `prompt`,
`outputQuality`, `extendDurationMs`, `resolution`, `enableBgm`, `elementIds`, and
one `endImageMediaId` or `uploadedEndImage`.

`extendDurationMs` is **additional** footage. The completed output includes the
source and continuation. `high` accepts `1000–15000`; `ultra` and `ultraS` accept
`4000–30000`, in whole-second increments. `best` is unsupported. Resolution
constraints are the same as I2V/T2V. Omit `prompt` for automatic continuation.
`modelId` and standalone voice inputs are not accepted.

## Video cloning and editing

### clone\_video

Required: exactly one `sourceMediaId` or `uploadedVideo`, plus an accessible
portrait `modelId` or separate identity image (`referenceImageMediaId` or
`uploadedReferenceImage`). Optional: `prompt` (nonblank, up to 4096 characters),
`outputQuality`, `resolution`, `preserveOptions`, `elementIds`.

Qualities are `best`, `ultra`, `ultraS`. Resolution is `SD`, `HD`, or `FHD`; `SD`
requires `best`. Source duration must be `4–15` seconds for `best` or `4–30`
seconds for `ultra`/`ultraS`; source dimensions/aspect are validated during
generation. Image element limits are 7 for `best` or 28 for `ultra`/`ultraS`,
after reserving identity and composite image slots.

`preserveOptions` is a unique array of `outfit`, `background`, `style`, `motion`,
`product`; omission selects all five. No output duration or ratio argument is
accepted.

### edit\_character and edit\_motion

Required: exactly one `sourceMediaId` or `uploadedVideo`, plus an accessible
ready portrait `modelId` or separate ready identity image
(`referenceImageMediaId` or `uploadedReferenceImage`). Optional: `prompt`
(nonblank, up to 4096 characters), `outputQuality`, `resolution`.

The source needs known positive dimensions and duration up to 30 seconds. These
tools do not expose `elementIds` or accept prompt element tags.

| Tool | `best` resolution | `ultra` resolution | `ultraS` resolution |
| - | - | - | - |
| `edit_character` | `SD`, `HD`, `FHD` | `HD`, `FHD`, `QHD` | `HD`, `FHD`, `QHD` |
| `edit_motion` | `SD`, `HD`, `FHD` | `HD`, `FHD` | `HD`, `FHD`, `QHD` |

### edit\_everything

Required: exactly one `sourceMediaId` or `uploadedVideo` and plain nonblank
`prompt` (up to 4096 characters). Optional: `outputQuality`, `resolution`,
`elementIds`, `voiceModelId`, `voiceModelIds`. Dialogue stays in `prompt`; this
tool has no `voiceScript` argument and does not accept `modelId`.

`best` accepts `SD`/`HD`/`FHD` and a positive source duration up to 15 seconds.
`ultra`/`ultraS` accept `HD`/`FHD`/`QHD` and source duration `4–30` seconds.
`best` supports at most 9 image references and rejects video elements.
`ultra`/`ultraS` use each element's first resource and allow up to 30 images,
10 video clips totaling 30 seconds **including the source**, and up to 5
combined selected voices and independent audio references (30-second audio
budget). `best` uses a maximum of 3 combined voice/audio references and a
15-second audio budget. Voice IDs deduplicate in scalar-first order;
independent audio and sampled voice references share the budget.

## Element reference limits for video

Reference support depends on quality, duration, and the selected workflow.
Source, model, and end images count toward image budgets. Unavailable, pending,
duplicate, unbound, or excessive references are rejected before submission.

For `high` I2V/T2V with elements, requested durations of at least four seconds
use a 9-image budget and up to 3 audio references totaling 15 seconds; video
elements are rejected. Shorter `high` requests use a different route with up to
9 images, 3 videos, 3 audios, and 12 total files; audio references share a
15-second budget and video preprocessing fits `2–15` seconds. `high` extension
does not accept elements. `best` I2V/T2V does not support element references.

The `ultra`/`ultraS` I2V/T2V routes for durations of at least four seconds use
each element's first resource and support a 30-image budget, 10 video clips
totaling at most 30 seconds, and 10 audio clips totaling at most 30 seconds.
Each video reference must have known dimensions and `2–30` second duration.
Short two/three-second routes use recovery limits of 10 images including
source/end frames, 5 video references totaling 15 seconds, and 5 audio references
within a 15-second budget. Video references require known dimensions, a valid
URL, `1–15` second duration, and aspect ratio at most `8:1`.

`ultra`/`ultraS` extension reserves one video clip and five seconds for its source,
leaving up to 9 element videos totaling 25 seconds. The image budget is 30 and
includes an end frame if supplied; audio references retain the 30-second budget.

## Speech-driven video

### talking\_avatar

Required: exactly one ready `sourceMediaId` or `uploadedImage`, plus exactly one
audio route: `audioMediaId`, `uploadedAudio`, or paired `voiceModelId` and
`voiceScript`. Optional: `modelId`, `prompt` (up to 4096 characters), `emotion`,
`outputQuality`, `resolution`.

| Quality | Resolution | Audio or estimated script duration |
| - | - | - |
| `best` (default) | `HD` | Positive, up to 900 seconds |
| `ultra` | `FHD` | Positive, up to 900 seconds |
| `ultraS` | `HD`, `FHD`, `QHD` | 4–180 seconds |

Supplied audio needs a known positive duration. Scripts use an estimated
duration check before submission. `emotion` is supported only with the script
route: `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`.
Voice models must be accessible and ready. Prompt element tags are unsupported.

### lip\_sync

Required: exactly one ready `sourceMediaId` or `uploadedVideo`, plus exactly one
audio route: `audioMediaId`, `uploadedAudio`, or paired `voiceModelId` and
`voiceScript`. Optional: `modelId`, `resolution` (`HD` or default `FHD`).

Source dimensions and duration must be known and positive. Supplied audio must
have a known positive duration up to 900 seconds and may outlast the source.
The script route validates estimated duration before billing. `FHD` uses
upscaling. This tool exposes no `prompt`, `emotion`, or `outputQuality` argument.

## Results and errors

Every generation tool above returns `taskId`, `contentId`, `status`, and
`terminal`. `get_generation_result` requires only `taskId` and reads your own
root content-generation task. It does not submit work or spend generation
credits.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "get_generation_result",
    "arguments": { "taskId": "example-task-id" }
  }
}
```

Replace the synthetic task ID with the returned receipt. Status values are
`onHold`, `preparing`, `preprocessing`, `running`, `paused`, `finished`,
`cancelled`, `error`, `blocked`. Terminal outcomes are `finished`, `cancelled`,
`error`, and `blocked`; only `finished` exposes final permitted media.

Result fields add `outputs` and nullable `error`. Each output has `mediaId`,
`type` (`image`, `video`, `audio`), `viewUrl`, `downloadUrl`, and optional
`width`, `height`, `durationMs`. Output URLs are temporary and can reflect the
account's watermark rules. Read again for fresh URLs. Before successful
completion, `outputs` is empty; terminal failures return sanitized
`GENERATION_FAILED` details.

| Tool error | Meaning and handling |
| - | - |
| `INVALID_ARGUMENTS`, `PROMPT_FORMAT_INVALID` | MCP preflight rejected the inputs before generation. Correct them before submitting. |
| `INSUFFICIENT_CREDITS` | Generation initialization was rejected for insufficient credits. |
| `INSUFFICIENT_CREDITS_AFTER_AUTO_RELOAD` | Generation initialization was rejected after auto-reload failed to provide enough credits. This does not prove an independently attempted reload payment was uncharged. |
| `GENERATION_SUBMISSION_UNCONFIRMED` | Submission or receipt outcome is uncertain. Reconcile history; do not automatically retry. |
| `GENERATION_NOT_FOUND` | The requested task is unavailable or not your own root content task. |
| `GENERATION_READ_FAILED` | Reading failed. Retry the same result lookup without creating new work. |

Model tasks have a separate [status tool](/mcp/library-and-elements#character-models).


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