Shared schema definitions
Source-generated field definitions, nested types, defaults, required flags, and constraints for this contract.
On this page
A dash means no default is declared, not a null value. A field can be optional in JSON Schema but conditionally required by the documented workflow. Model-specific options still require live capability discovery.
AnimationCreateRequest
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
export |
ExportOptions | No | {"frame_count":24,"output_formats":["spritesheet"],"output_height":512,"output_width":512,"transparent":{"enabled":false},"unity":{"pivot":"bottom_center","pixels_per_unit":100}} |
— | Export after video generation. Alpha-bearing formats require an alpha_key source; compatible formats automatically enable its transparent export. |
input |
GenerationInput | Yes | — | — | Images owned by the caller or supplied for this generation. |
metadata |
object |
No | {} |
— | Caller metadata: simple string/number/boolean/null values, at most 4 KiB JSON. Do not store secrets. |
negative_prompt |
string |
No | "" |
maxLength: 4000 |
Optional exclusions, only when the model supports negative prompts. |
prompt |
string |
No | "" |
maxLength: 8000 |
Motion instruction; nonempty when the model requires a prompt. Keep private prompts out of logs. |
selection |
Selection | No | {"duration_seconds":null,"mode":"full","start_seconds":0} |
— | Interval selected after generation; full by default. |
video |
VideoOptions | No | {"duration_seconds":null,"input_canvas":null,"model":null,"ratio":null,"resolution":null,"seed":null,"style_preset":null,"transparency":{"key_color":null,"key_selection":"auto","mode":"standard"},"watermark":null} |
— | Model-compatible generation settings. |
AssetResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
byte_size |
integer |
Yes | — | — | Expected file size in bytes. |
created_at |
string |
Yes | — | format: date-time |
Creation timestamp in UTC. |
download_expires_at |
string |
Yes | — | format: date-time |
Signed URL expiry in UTC; refresh via asset lookup when expired. |
download_url |
string |
Yes | — | — | Sensitive short-lived signed URL. Download without a Bearer header, including after redirects; never log the URL. |
format |
string |
Yes | — | — | Artifact format; inspect actual outputs rather than assuming an array order. |
id |
string |
Yes | — | format: uuid |
Stable public asset ID; use it to refresh download metadata. |
mime_type |
string |
Yes | — | — | Asset media type. |
object |
string |
No | "asset" |
const: "asset" |
— |
Base64ImageInput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
data |
string |
Yes | — | minLength: 4 |
Pure Base64 without a data URL prefix; decoded limits: 10 MiB per image, 20 MiB total. |
media_type |
string |
Yes | — | enum: "image/png", "image/jpeg", "image/webp" |
Actual image MIME type. |
type |
string |
Yes | — | const: "base64" |
— |
CreditUsage
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
charged |
integer |
Yes | — | — | Net charged credits. Confirmed provider moderation rejection is refunded; cancellation alone is not a refund. |
held |
integer |
Yes | — | — | Credits currently reserved, not an additional charge to sum with charged. |
quoted |
integer |
Yes | — | — | Quoted total, not necessarily the final charge. |
refunded |
integer |
No | 0 |
— | Credits returned after a charge; already excluded from charged. Not a cash refund. |
released |
integer |
No | 0 |
— | Credits returned from an uncommitted hold. |
status |
string / null |
No | null |
— | Billing state: held, charged, released, refunded, or managed for internal child tasks. |
ExportOptions
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
frame_count |
integer |
No | 24 |
minimum: 1; maximum: 240 |
Number of frames sampled over the selected interval, not an FPS field. |
output_formats |
array<string> |
No | ["spritesheet"] |
minItems: 1; items: enum: "clip_video", "webm_alpha", "prores_4444", "frames_zip", "spritesheet", "spritesheet_json", "unity_meta", "unity_pack", "godot_pack", "unreal_paper2d_pack", "cocos_creator_pack" |
Requested asset formats; defaults to spritesheet. Duplicates are removed. Metadata needs its matching texture. |
output_height |
integer |
No | 512 |
minimum: 64; maximum: 1024 |
Output frame height in pixels. |
output_width |
integer |
No | 512 |
minimum: 64; maximum: 1024 |
Output frame width in pixels. |
transparent |
ExportTransparency | No | {"enabled":false} |
— | Use the enabled object form. Legacy booleans are accepted but normalized to this object. |
unity |
UnityOptions | No | {"pivot":"bottom_center","pixels_per_unit":100} |
— | Settings for Unity-specific metadata and packs. |
ExportTransparency
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
enabled |
boolean |
No | false |
— | Transparent processing for compatible outputs; requires an alpha_key source and does not make MP4 transparent. |
FileImageInput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
file_id |
string |
Yes | — | format: uuid |
Owned public file ID from POST /files or complete_image_upload; not a Studio upload ID. |
type |
string |
Yes | — | const: "file" |
— |
GenerationInput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
first_frame |
FileImageInput / Base64ImageInput / UrlImageInput | Yes | — | discriminator: type |
Required starting image; use the type discriminator to select an input representation. |
last_frame |
FileImageInput / Base64ImageInput / UrlImageInput / null |
No | null |
discriminator: type |
Optional end image; the selected model must support first/last-frame mode. |
reference_images |
array<FileImageInput / Base64ImageInput / UrlImageInput> | No | [] |
maxItems: 8; items: discriminator: type |
Additional references, excluding the first frame. The live model can impose a smaller limit. |
GenerationTransparency
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
key_color |
string / null |
No | null |
— | Temporary key color when using manual selection; normally leave automatic selection enabled. |
key_selection |
string |
No | "auto" |
enum: "auto", "manual" |
How the temporary key color is selected. |
mode |
string |
No | "standard" |
enum: "standard", "alpha_key" |
standard keeps the scene; alpha_key requires meaningful alpha in all active input images. Raw videos remain opaque. |
InputCanvasOptions
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
aspect_ratio |
string |
No | "follow_output" |
enum: "follow_output", "source" |
Follow the output ratio or preserve the source ratio. |
background |
string |
No | "auto" |
enum: "auto", "transparent", "solid" |
Canvas extension background strategy. |
background_color |
string / null |
No | null |
pattern: ^#[0-9A-Fa-f]{6}$ |
Six-digit RGB color for a solid extension. |
enabled |
boolean |
No | true |
— | Whether to prepare an expanded input canvas. |
position_x |
number |
No | 0.5 |
minimum: 0; maximum: 1 |
Normalized horizontal source position. |
position_y |
number |
No | 0.5 |
minimum: 0; maximum: 1 |
Normalized vertical source position. |
source_scale |
number |
No | 0.8 |
minimum: 0.5; maximum: 1 |
Source subject scale within the canvas. |
McpQuoteOutput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
breakdown |
object |
Yes | — | — | Public cost components. |
credits |
integer |
Yes | — | — | Quoted credits; show the amount to the user before generation. |
expires_at |
string |
Yes | — | format: date-time |
Quote expiry; re-quote and confirm if it expires or price changes. |
quote_id |
string |
Yes | — | format: uuid |
Short-lived quote owned by this user and OAuth client; can bind to one logical generation key. |
McpUploadCompleteOutput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
byte_size |
integer |
Yes | — | — | Validated image byte count. |
file_id |
string |
Yes | — | format: uuid |
Reusable owned public file ID for request.input.first_frame. |
mime_type |
string |
Yes | — | — | Validated image MIME type. |
sha256 |
string |
Yes | — | — | SHA-256 of the uploaded image bytes. |
McpUploadPrepareOutput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
expires_at |
string |
Yes | — | format: date-time |
Upload URL expiry. |
headers |
object |
Yes | — | — | Exact transfer headers; do not add MCP tokens or API Bearer credentials. |
max_bytes |
integer |
Yes | — | — | Maximum accepted upload byte count. |
method |
string |
No | "PUT" |
const: "PUT" |
HTTP method the client must use for the byte transfer. |
upload_id |
string |
Yes | — | format: uuid |
Upload session ID for complete_image_upload, not the final file_id. |
upload_url |
string |
Yes | — | — | Sensitive short-lived upload URL. Transfer actual bytes; do not publish this URL. |
ModelCapabilities
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
aspect_ratio_mode |
string |
Yes | — | — | Provider's aspect-ratio handling mode. |
default_duration_seconds |
integer |
Yes | — | — | Default generation duration in seconds. |
default_ratio |
string / null |
Yes | — | — | Default ratio, or null when not applicable. |
default_resolution |
string / null |
Yes | — | — | Default resolution, or null when not applicable. |
durations |
array<integer> |
Yes | — | — | Supported generation durations in seconds; also inspect resolution-specific constraints. |
durations_by_resolution |
object |
No | {} |
— | Resolution-specific supported durations in seconds. |
id |
string |
Yes | — | — | Stable provider:model selector for requests; use the live catalog. |
label |
string |
Yes | — | — | Human-readable model label. |
max_reference_images |
integer |
Yes | — | — | Model reference-image capacity; the first frame occupies the first reference slot in reference mode. |
model |
string |
Yes | — | — | Model identifier within the provider. |
modes |
array<string> |
Yes | — | — | Supported input modes, such as first_frame, first_last_frame, or reference_images. |
provider |
string |
Yes | — | — | Public provider identifier. |
ratios |
array<string> |
Yes | — | — | Supported aspect ratio values; check ratios_by_mode where present. |
ratios_by_mode |
object |
No | {} |
— | Input-mode-specific supported ratios. |
reference_image_duration_seconds |
integer / null |
Yes | — | — | Required duration for reference mode, when constrained. |
requires_prompt |
boolean |
Yes | — | — | Whether prompt must be nonempty. |
resolutions |
array<string> |
Yes | — | — | Supported resolution values. |
returns_last_frame |
boolean |
Yes | — | — | Whether the model can return a last-frame asset. |
supports_first_frame |
boolean |
Yes | — | — | Whether a first-frame input is supported. |
supports_last_frame |
boolean |
Yes | — | — | Whether a last-frame input is supported. |
supports_negative_prompt |
boolean |
Yes | — | — | Whether negative_prompt is supported. |
supports_reference_images |
boolean |
Yes | — | — | Whether reference-image mode is supported. |
supports_seed |
boolean |
Yes | — | — | Whether seed is supported. |
supports_watermark |
boolean |
Yes | — | — | Whether the watermark setting is supported. |
ModelsResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
data |
array<ModelCapabilities> | Yes | — | — | Currently enabled models; do not hard-code this list in a client. |
object |
string |
No | "list" |
const: "list" |
— |
Selection
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
duration_seconds |
number / null |
No | null |
exclusiveMinimum: 0 |
Required when mode=range; positive interval length in seconds. |
mode |
string |
No | "full" |
enum: "full", "range" |
full uses the complete source; range requires duration_seconds. |
start_seconds |
number |
No | 0 |
minimum: 0 |
Range start in seconds from the source beginning. |
TaskError
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
code |
string |
Yes | — | — | Machine-readable task error code. |
message |
string |
Yes | — | — | Human-readable summary, not a stable branching key. |
retryable |
boolean |
No | false |
— | Whether retry may help; inspect partial outputs before creating a new paid task. |
TaskResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
created_at |
string |
Yes | — | format: date-time |
UTC acceptance timestamp. |
credits |
CreditUsage | Yes | — | — | Quoted, reserved, and charged credit states. |
error |
TaskError / null |
No | null |
— | Task failure details, independently of any usable outputs. |
finished_at |
string / null |
No | null |
format: date-time |
UTC terminal timestamp when known. |
id |
string |
Yes | — | format: uuid |
Persist this task ID immediately after create; poll it instead of creating again. |
metadata |
object |
No | {} |
— | Caller-provided metadata. |
normalized_input |
object |
No | {} |
— | Normalized public input; may contain private prompts or image references. Do not log wholesale. |
object |
string |
Yes | — | enum: "video_generation", "animation_export", "animation" |
Public task resource type. |
outputs |
array<AssetResponse> | No | [] |
— | Available assets, including partial outputs on failed/cancelled tasks. Always inspect them at a terminal state. |
progress |
number |
Yes | — | minimum: 0; maximum: 1 |
Fraction from 0 to 1, not a completion-time estimate. |
stage |
string / null |
No | null |
enum: "queued", "video_generation", "animation_export", "completed" |
Current pipeline stage when available. |
started_at |
string / null |
No | null |
format: date-time |
UTC production start when known. |
status |
string |
Yes | — | enum: "queued", "running", "cancelling", "succeeded", "failed", "cancelled" |
succeeded, failed, and cancelled are terminal; cancelling is not terminal. |
UnityOptions
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
pivot |
string |
No | "bottom_center" |
const: "bottom_center" |
Supported Unity sprite pivot. |
pixels_per_unit |
integer |
No | 100 |
minimum: 1; maximum: 1000 |
Unity texture pixels per world unit. |
UrlImageInput
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
type |
string |
Yes | — | const: "url" |
— |
url |
string |
Yes | — | minLength: 9; maxLength: 2048 |
Public HTTPS image on port 443, without credentials or fragments. Private networks and unsafe redirects are rejected. Keep bytes stable across retries. |
VideoOptions
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
duration_seconds |
number / null |
No | null |
exclusiveMinimum: 0 |
Seconds; choose a supported duration for the model and resolution. Omission uses its default. |
input_canvas |
InputCanvasOptions / null |
No | null |
— | Optional input framing; omit to keep the source framing. |
model |
string / null |
No | null |
— | provider:model ID from GET /models; omission uses the configured default model. |
ratio |
string / null |
No | null |
— | Aspect ratio supported by the current model and input mode. |
resolution |
string / null |
No | null |
— | Resolution value from the live model catalog. |
seed |
integer / null |
No | null |
minimum: 0; maximum: 2147483647 |
Optional seed only for models advertising seed support; not a universal determinism guarantee. |
style_preset |
string / null |
No | null |
— | Optional style preset supported by the selected provider/model. |
transparency |
GenerationTransparency | No | {"key_color":null,"key_selection":"auto","mode":"standard"} |
— | Source transparency workflow; transparent exports require alpha_key. |
watermark |
boolean / null |
No | null |
— | Optional watermark setting; check the model capability. |
Was this page helpful?
No search queries, code, or free text are collected. This switch controls documentation interactions only; general site analytics follow the privacy policy. Privacy policy