Generation tools

Generation tools submit asynchronous work and return a task receipt. They consume credits and may trigger configured automatic reload. Submit once and follow the returned task.

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.

Common inputs

Use the current tools/list schema and 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.
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:

{
  "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:

{
  "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 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.

{
  "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.

Get started

Core concepts

Workflows

MCP API

GraphQL API

Usage and troubleshooting

Common inputs

Image prompt resource

Image tools

create_image

create_portrait_master

edit_image

clone_image

Video generation and extension

create_image_to_video

create_text_to_video

extend_video

Video cloning and editing

clone_video

edit_character and edit_motion

edit_everything

Element reference limits for video

Speech-driven video

talking_avatar

lip_sync

Results and errors

​Common inputs

​Image prompt resource

​Image tools

​create_image

​create_portrait_master

​edit_image

​clone_image

​Video generation and extension

​create_image_to_video

​create_text_to_video

​extend_video

​Video cloning and editing

​clone_video

​edit_character and edit_motion

​edit_everything

​Element reference limits for video

​Speech-driven video

​talking_avatar

​lip_sync

​Results and errors

Common inputs

Image prompt resource

Image tools

create_image

create_portrait_master

edit_image

clone_image

Video generation and extension

create_image_to_video

create_text_to_video

extend_video

Video cloning and editing

clone_video

edit_character and edit_motion

edit_everything

Element reference limits for video

Speech-driven video

talking_avatar

lip_sync

Results and errors