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.
AccountAPIKey
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
id |
string |
Yes | — | format: uuid |
Identity of the authenticated key, not its secret. Idempotency is scoped to this identity. |
scopes |
array<string> |
Yes | — | — | Permissions granted to this key. |
AccountLimits
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
concurrency |
integer |
Yes | — | — | Maximum concurrent jobs across this account. |
create_per_minute |
integer |
Yes | — | — | Account-wide create requests per minute. |
other_per_minute |
integer |
Yes | — | — | Account-wide other requests per minute. |
queue |
integer |
Yes | — | — | Maximum queued jobs across this account. |
AccountPlan
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
cancel_at_period_end |
boolean |
Yes | — | — | Whether the current paid subscription will stop renewing; false for registered access. |
code |
string |
Yes | — | — | Current developer access tier: registered, basic, expert, or ultra. |
current_period_end |
string / null |
Yes | — | format: date-time |
Paid subscription period end in UTC, or null for registered access. |
AccountResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
api_key |
AccountAPIKey | Yes | — | — | Current key identity and scopes; never the key secret. |
id |
string |
Yes | — | format: uuid |
Authenticated account ID. |
limits |
AccountLimits | Yes | — | — | Limits are shared by every key on this account. |
object |
string |
No | "account" |
const: "account" |
— |
plan |
AccountPlan | Yes | — | — | Current developer access tier and optional subscription period. |
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. |
AnimationExportCreateRequest
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}} |
— | Output formats and processing settings. |
metadata |
object |
No | {} |
— | Simple scalar/null metadata; at most 4 KiB JSON, no credentials. |
selection |
Selection | No | {"duration_seconds":null,"mode":"full","start_seconds":0} |
— | Source interval to export. |
source_video_asset_id |
string |
Yes | — | format: uuid |
Owned source video asset ID, not a task ID. Reuse an existing video to avoid generating motion again. |
APIError
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
code |
string |
Yes | — | — | Stable machine-readable error code. |
details |
object |
Yes | — | — | Public error-specific fields; inspect without logging private inputs. |
message |
string |
Yes | — | — | Human-readable explanation; do not branch on exact text. |
param |
string / null |
No | — | — | Related public parameter, if known. |
request_id |
string / null |
Yes | — | — | Public support correlation ID, not a credential. |
retryable |
boolean |
Yes | — | — | Retry may help; still preserve idempotency and respect Retry-After. |
APIErrorEnvelope
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
error |
APIError | Yes | — | — | — |
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" |
— |
Body_create_file_v1_files_post
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
file |
string |
Yes | — | format: binary |
PNG, JPEG, or WebP image bytes; validated before returning a public file ID. |
CreditsBalanceResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
available |
integer |
Yes | — | — | Currently available account credits; not a feature-entitlement flag. |
object |
string |
No | "credit_balance" |
const: "credit_balance" |
— |
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" |
— |
FileResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
byte_size |
integer |
Yes | — | — | Stored image byte count. |
created_at |
string |
Yes | — | format: date-time |
UTC upload creation time. |
height |
integer |
Yes | — | — | Decoded image height in pixels. |
id |
string |
Yes | — | format: uuid |
Reusable public file ID for type=file inputs. |
mime_type |
string |
Yes | — | — | Validated image media type. |
object |
string |
No | "file" |
const: "file" |
— |
sha256 |
string |
Yes | — | — | SHA-256 of the image bytes. |
width |
integer |
Yes | — | — | Decoded image width in pixels. |
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. |
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" |
— |
QuoteResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
breakdown |
object |
No | {} |
— | Public cost components; use credits as the quoted total. |
credits |
integer |
Yes | — | — | Current estimated credits. No price lock or spend authorization; creation recalculates the quote. |
object |
string |
No | "quote" |
const: "quote" |
— |
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. |
TaskListResponse
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
data |
array<TaskResponse> | Yes | — | — | Owned tasks in this page. |
next_cursor |
string / null |
No | null |
— | Opaque next-page cursor; null means no next page. Pass it unchanged. |
object |
string |
No | "list" |
const: "list" |
— |
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. |
VideoGenerationCreateRequest
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
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. |
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. |
VideoGenerationQuoteRequest
Unknown fields are rejected.
| Field | Type | Required | Default | Constraints | Meaning |
|---|---|---|---|---|---|
has_last_frame |
boolean |
No | false |
— | Whether the planned request includes a last frame. |
reference_image_count |
integer |
No | 0 |
minimum: 0; maximum: 8 |
Number of additional references, excluding the first frame. |
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} |
— | Generation options to estimate; must match the later create. |
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