{ "components": { "headers": { "RequestID": { "description": "The identifier of this request: the valid value you sent, or its replacement.", "required": true, "schema": { "maxLength": 64, "minLength": 1, "pattern": "^[0-9A-Za-z][0-9A-Za-z._-]*$", "type": "string" } } }, "parameters": { "AssetID": { "description": "ID of an asset owned by the signed-in team.", "in": "path", "name": "asset_id", "required": true, "schema": { "$ref": "#/components/schemas/AssetID" } }, "BillingCursor": { "description": "Opaque value for fetching the next page of permanent billing events.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 256, "minLength": 1, "type": "string" } }, "BillingPageSize": { "description": "Maximum number of billing events in this page.", "in": "query", "name": "page_size", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, "IdempotencyKey": { "description": "Generate a new value for every new request and save it; it starts with a letter or digit. When the outcome is unknown, retry with the same key and the original body to get the original response; the same key with a different body returns 409 idempotency_conflict. Keys belong to your team, not to one API key.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "pattern": "^[0-9A-Za-z][0-9A-Za-z._:-]*$", "type": "string" } }, "RequestID": { "description": "Your own request identifier. An invalid or repeated value is replaced; the value used comes back in the X-Request-ID response header.", "in": "header", "name": "X-Request-ID", "required": false, "schema": { "type": "string" } }, "TaskID": { "description": "ID of the video task to retrieve", "in": "path", "name": "task_id", "required": true, "schema": { "$ref": "#/components/schemas/TaskID" } }, "VideoTaskCursor": { "description": "Use next_cursor from the preceding page. A value not issued for this team's task list returns invalid_request.", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 256, "minLength": 1, "type": "string" } }, "VideoTaskPageSize": { "description": "Maximum number of tasks to return on this page.", "in": "query", "name": "page_size", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } }, "responses": { "AssetBadRequestResponse": { "content": { "application/json": { "examples": { "invalid": { "value": { "error": { "code": "invalid_request", "message": "invalid asset request" }, "trace_id": "trace_asset_invalid" } }, "source": { "value": { "error": { "code": "source_url_not_allowed", "message": "source URL is not allowed" }, "trace_id": "trace_asset_source" } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "enum": [ "invalid_request", "source_url_not_allowed" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The request is invalid or the source address fails the HTTPS fetch policy.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "AssetIdempotencyConflictResponse": { "content": { "application/json": { "example": { "error": { "code": "idempotency_conflict", "message": "idempotency key conflicts with the original request" }, "trace_id": "trace_asset_conflict" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "idempotency_conflict" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "Your team already used this idempotency value for a different canonical asset registration request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "AssetIntakeLimitResponse": { "content": { "application/json": { "examples": { "intake": { "value": { "error": { "code": "asset_intake_rate_limit_exceeded", "message": "asset intake rate limit exceeded" }, "trace_id": "trace_asset_intake" } }, "quota": { "value": { "error": { "code": "asset_storage_quota_exceeded", "message": "asset storage quota exceeded" }, "trace_id": "trace_asset_quota" } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "enum": [ "asset_storage_quota_exceeded", "asset_intake_rate_limit_exceeded" ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The asset cannot be accepted within your team's stored-byte allowance or intake capacity.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "AssetNotFoundResponse": { "content": { "application/json": { "example": { "error": { "code": "asset_not_found", "message": "asset not found" }, "trace_id": "trace_asset_missing" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "asset_not_found" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "No visible asset matches this ID. Unknown, deleted and other teams' IDs receive the same response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "AssetPermissionDeniedResponse": { "content": { "application/json": { "example": { "error": { "code": "permission_denied", "message": "permission denied" }, "trace_id": "trace_asset_permission" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "permission_denied" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "This API key does not have service.use permission.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "AssetReplayExpiredResponse": { "content": { "application/json": { "example": { "error": { "code": "idempotency_replay_expired", "message": "asset create replay expired" }, "trace_id": "trace_asset_expired" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "idempotency_replay_expired" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The saved acceptance response is too old to replay exactly. Repeating the request will not create another asset.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "BadRequestResponse": { "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "request parameters are invalid" }, "trace_id": "trace_error_example" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "invalid_request", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The submitted request is not valid.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "CancellationConflictResponse": { "content": { "application/json": { "examples": { "idempotency_conflict": { "value": { "error": { "code": "idempotency_conflict", "message": "the idempotency key targets a different cancellation operation" }, "trace_id": "trace_error_example" } }, "idempotency_replay_expired": { "value": { "error": { "code": "idempotency_replay_expired", "message": "the exact cancellation snapshot is no longer available" }, "trace_id": "trace_error_example" } }, "task_not_cancellable": { "value": { "error": { "code": "task_not_cancellable", "message": "the terminal task has no cancellation operation" }, "trace_id": "trace_error_example" } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "enum": [ "task_not_cancellable", "idempotency_conflict", "idempotency_replay_expired" ], "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The idempotency key belongs to a different request, or the finished task has no cancellation operation to refer to.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "CreateVideoGenerationBadRequestResponse": { "content": { "application/json": { "examples": { "asset_not_found": { "value": { "error": { "code": "asset_not_found", "message": "a referenced asset was not found" }, "trace_id": "trace_error_example" } }, "asset_unusable": { "value": { "error": { "code": "asset_unusable", "message": "a referenced asset cannot be used for this request" }, "trace_id": "trace_error_example" } }, "callback_target_not_verified": { "value": { "error": { "code": "callback_target_not_verified", "message": "the callback URL is not a verified callback target of the team" }, "trace_id": "trace_error_example" } }, "input_video_duration_exceeded": { "value": { "error": { "code": "input_video_duration_exceeded", "message": "the total input video duration exceeds the model's limit" }, "trace_id": "trace_error_example" } }, "invalid_request": { "value": { "error": { "code": "invalid_request", "message": "request parameters are invalid" }, "trace_id": "trace_error_example" } }, "unsupported_capability": { "value": { "error": { "code": "unsupported_capability", "details": { "capability": "output.resolution.1080p", "param": "resolution" }, "message": "the requested capabilities are not available for this model" }, "trace_id": "trace_error_example" } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "allOf": [ { "else": { "not": { "required": [ "details" ] } }, "if": { "properties": { "code": { "const": "unsupported_capability" } }, "required": [ "code" ] }, "then": { "required": [ "details" ] } } ], "properties": { "code": { "enum": [ "invalid_request", "asset_not_found", "asset_unusable", "input_video_duration_exceeded", "callback_target_not_verified", "unsupported_capability" ], "type": "string" }, "details": { "oneOf": [ { "additionalProperties": false, "properties": { "capability": { "maxLength": 64, "pattern": "^(input|output|control)(\\.[0-9a-z][0-9a-z_:]*){1,2}$", "type": "string" }, "param": { "enum": [ "content", "draft", "duration", "execution_expires_after", "generate_audio", "omni_reference_task_type", "output_format", "priority", "ratio", "resolution", "return_last_frame", "safety_identifier", "seed" ], "type": "string" } }, "required": [ "capability", "param" ], "type": "object" }, { "additionalProperties": false, "properties": { "capabilities": { "items": { "maxLength": 64, "pattern": "^(input|output|control)(\\.[0-9a-z][0-9a-z_:]*){1,2}$", "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "params": { "items": { "enum": [ "content", "draft", "duration", "execution_expires_after", "generate_audio", "omni_reference_task_type", "output_format", "priority", "ratio", "resolution", "return_last_frame", "safety_identifier", "seed" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "capabilities", "params" ], "type": "object" } ] } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The format or parameters are wrong, or a referenced asset or callback address cannot be used. Such a request creates no task and reserves nothing; only unsupported_capability carries details.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "DependencyUnavailableResponse": { "content": { "application/json": { "example": { "error": { "code": "dependency_unavailable", "message": "service is not ready" }, "trace_id": "trace_error_example" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "dependency_unavailable", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The service is temporarily unavailable. Retry the same request later.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "FundingIntakeUnavailableResponse": { "content": { "application/json": { "examples": { "dependency_unavailable": { "value": { "error": { "code": "dependency_unavailable", "message": "service is not ready" }, "trace_id": "trace_error_example" } }, "funding_intake_closed": { "value": { "error": { "code": "funding_intake_closed", "message": "new funding intake is temporarily closed" }, "trace_id": "trace_error_example" } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "enum": [ "dependency_unavailable", "funding_intake_closed" ], "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The service is temporarily unavailable, or new tasks are paused. An exact replay of an accepted request still returns its response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "IdempotencyConflictResponse": { "content": { "application/json": { "examples": { "asset_not_ready": { "value": { "error": { "code": "asset_not_ready", "message": "a referenced asset is not ready" }, "trace_id": "trace_error_example" } }, "idempotency_conflict": { "value": { "error": { "code": "idempotency_conflict", "message": "the idempotency key was used with a different canonical request" }, "trace_id": "trace_error_example" } }, "idempotency_replay_expired": { "value": { "error": { "code": "idempotency_replay_expired", "message": "the exact replay projection is no longer available" }, "trace_id": "trace_error_example" } }, "key_provisioning_incomplete": { "value": { "error": { "code": "key_provisioning_incomplete", "message": "the API key was not fully provisioned; delete it and create a new key" }, "trace_id": "trace_error_example" } } }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "enum": [ "idempotency_conflict", "idempotency_replay_expired", "key_provisioning_incomplete", "asset_not_ready" ], "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The idempotency key conflicts or its replay has expired, the API key is not ready, or an asset is still processing. This request creates no task and reserves nothing; for an API key that is not ready, delete it and create another.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "InternalErrorResponse": { "content": { "application/json": { "example": { "error": { "code": "internal_error", "message": "internal server error" }, "trace_id": "trace_error_example" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "internal_error", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "Internal error. Retry as is; for create and cancel requests, use the same Idempotency-Key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "RateLimitResponse": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "request rate limit exceeded" }, "trace_id": "trace_error_example" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "rate_limited", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The request rate limit blocks this read operation.", "headers": { "Retry-After": { "required": false, "schema": { "maximum": 3600, "minimum": 1, "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "RequestLimitResponse": { "content": { "application/json": { "examples": { "asset_storage_quota_exceeded": { "value": { "error": { "code": "asset_storage_quota_exceeded", "message": "asset storage quota exceeded" }, "trace_id": "trace_error_example" } }, "insufficient_balance": { "value": { "error": { "code": "insufficient_balance", "details": { "currency": "USD", "estimated_usage_upper_bound": { "video_tokens": 111779 }, "meter_type": "seedance_video_generation", "price_version": "price_example_0001", "reserved_amount": "0.782453" }, "message": "available USD balance is below the required reservation" }, "trace_id": "trace_error_example" } }, "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "request rate limit exceeded" }, "trace_id": "trace_error_example" } } }, "schema": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "insufficient_balance", "type": "string" }, "details": { "$ref": "#/components/schemas/InsufficientBalanceDetails" } }, "required": [ "details" ], "type": "object" } }, "type": "object" } ] }, { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "rate_limited", "type": "string" } }, "type": "object" } }, "type": "object" } ] }, { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "asset_storage_quota_exceeded", "type": "string" } }, "type": "object" } }, "type": "object" } ] } ] } } }, "description": "The balance is too low, requests come too fast, or asset storage is full. When requests come too fast, wait for Retry-After before you retry.", "headers": { "Retry-After": { "required": false, "schema": { "maximum": 3600, "minimum": 1, "type": "integer" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "TaskNotFoundResponse": { "content": { "application/json": { "example": { "error": { "code": "task_not_found", "message": "task was not found" }, "trace_id": "trace_error_example" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "task_not_found", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "No task with this ID is visible to your team.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "UnauthorizedResponse": { "content": { "application/json": { "example": { "error": { "code": "authentication_failed", "message": "authentication failed" }, "trace_id": "trace_error_example" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "properties": { "error": { "properties": { "code": { "const": "authentication_failed", "type": "string" } }, "type": "object" } }, "type": "object" } ] } } }, "description": "The API key is missing or invalid. The WWW-Authenticate response header names the scheme to use.", "headers": { "WWW-Authenticate": { "required": true, "schema": { "const": "Bearer", "example": "Bearer", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } } }, "schemas": { "AssetFailureReason": { "description": "Reasons an asset can be unavailable", "enum": [ "source_url_not_allowed", "source_fetch_failed", "source_too_large", "media_type_mismatch", "media_constraints_violated", "review_rejected", "review_unavailable", "internal_error" ], "type": "string" }, "AssetID": { "description": "An asset owned by the signed-in team. Its ID starts with ast- followed by 32 lowercase hexadecimal digits, which cannot all be zero.", "maxLength": 36, "minLength": 36, "not": { "const": "ast-00000000000000000000000000000000" }, "pattern": "^ast-[0-9a-f]{32}$", "type": "string" }, "AssetIntakeModel": { "description": "Models that accept asset registration. This list is separate from the list of models available for video tasks.", "enum": [ "dreamina-seedance-2-0-260128", "dreamina-seedance-2-0-fast-260128", "dreamina-seedance-2-0-mini-260615" ], "type": "string" }, "AssetLocation": { "description": "Relative path for checking an asset", "format": "uri-reference", "maxLength": 47, "minLength": 47, "pattern": "^/v1/assets/ast-[0-9a-f]{32}$", "type": "string" }, "AssetReadResponse": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "const": "active" } } }, "then": { "allOf": [ { "if": { "properties": { "media_type": { "enum": [ "image", "video" ] } } }, "then": { "required": [ "width", "height" ] } }, { "if": { "properties": { "media_type": { "enum": [ "audio", "video" ] } } }, "then": { "required": [ "duration_ms" ] } }, { "if": { "properties": { "media_type": { "const": "image" } } }, "then": { "not": { "required": [ "duration_ms" ] } } }, { "if": { "properties": { "media_type": { "const": "audio" } } }, "then": { "not": { "anyOf": [ { "required": [ "width" ] }, { "required": [ "height" ] } ] } } } ], "not": { "required": [ "failure_reason" ] }, "required": [ "size_bytes", "sha256" ] } }, { "if": { "properties": { "status": { "const": "unavailable" } } }, "then": { "not": { "anyOf": [ { "required": [ "size_bytes" ] }, { "required": [ "sha256" ] }, { "required": [ "width" ] }, { "required": [ "height" ] }, { "required": [ "duration_ms" ] } ] }, "required": [ "failure_reason" ] } }, { "if": { "properties": { "status": { "const": "processing" } } }, "then": { "not": { "anyOf": [ { "required": [ "size_bytes" ] }, { "required": [ "sha256" ] }, { "required": [ "failure_reason" ] }, { "required": [ "width" ] }, { "required": [ "height" ] }, { "required": [ "duration_ms" ] } ] } } } ], "description": "For active assets, size_bytes and sha256 are required. Images and videos also include width and height; audio and video include duration_ms. Images omit duration_ms; audio omits dimensions. Active assets omit failure_reason. Unavailable assets include failure_reason and omit all these measurements. Processing assets omit both measurements and failure_reason.", "properties": { "asset_id": { "$ref": "#/components/schemas/AssetID" }, "created_at": { "$ref": "#/components/schemas/UnixTime" }, "duration_ms": { "minimum": 1, "type": "integer" }, "failure_reason": { "$ref": "#/components/schemas/AssetFailureReason" }, "height": { "minimum": 1, "type": "integer" }, "media_type": { "enum": [ "image", "audio", "video" ], "type": "string" }, "model": { "$ref": "#/components/schemas/AssetIntakeModel" }, "name": { "maxLength": 64, "minLength": 1, "not": { "pattern": "[\\u0000-\\u001F\\u007F-\\u009F\\u2028-\\u202E\\u2066-\\u2069]" }, "type": "string" }, "object": { "const": "asset", "type": "string" }, "sha256": { "$ref": "#/components/schemas/SHA256" }, "size_bytes": { "minimum": 1, "type": "integer" }, "status": { "enum": [ "processing", "active", "unavailable" ], "type": "string" }, "updated_at": { "$ref": "#/components/schemas/UnixTime" }, "width": { "minimum": 1, "type": "integer" } }, "required": [ "asset_id", "status", "object", "media_type", "model", "created_at", "updated_at" ], "type": "object" }, "BillingComponent": { "description": "Parts of a billable service", "enum": [ "generation_output", "reference_video", "reference_image", "reference_audio", "web_search", "other" ], "type": "string" }, "BillingCorrelationID": { "$ref": "#/components/schemas/StableID", "description": "ID for correlating billing records" }, "BillingEvent": { "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "adjustment_direction": { "type": "null" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/Money" }, { "not": { "const": "0.000000" } } ] }, "audit_reason": { "type": "null" }, "event_type": { "const": "hold_reduced", "type": "string" } }, "required": [ "billing_operation_id", "quote_revision_before", "quote_revision_after", "reservation_revision_before", "reservation_revision_after" ], "type": "object" }, { "properties": { "adjustment_direction": { "type": "null" }, "audit_reason": { "type": "null" }, "event_type": { "const": "charge_captured", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" }, "refund_amount": { "const": "0.000000", "type": "string" } }, "required": [ "event_type", "refund_amount", "funding_refund_amount", "receivable_amount", "receivable_direction", "adjustment_direction" ], "type": "object" }, { "properties": { "adjustment_direction": { "type": "null" }, "amount": { "const": "0.000000", "type": "string" }, "audit_reason": { "type": "null" }, "event_type": { "const": "charge_waived", "type": "string" } }, "type": "object" }, { "properties": { "adjustment_direction": { "enum": [ "debit", "credit" ], "type": "string" }, "audit_reason": { "maxLength": 1024, "minLength": 1, "type": "string" }, "event_type": { "const": "manual_adjustment", "type": "string" } }, "type": "object" }, { "properties": { "adjustment_direction": { "type": "null" }, "audit_reason": { "type": "null" }, "event_type": { "enum": [ "hold_created", "hold_increased", "supplemental_charge", "receivable_created", "receivable_payment", "receivable_reduced", "hold_released", "refund_posted" ], "type": "string" } }, "type": "object" } ] }, { "if": { "properties": { "event_type": { "enum": [ "hold_created", "hold_increased", "hold_reduced", "hold_released" ], "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "charge_amount": { "const": "0.000000", "type": "string" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "event_type": { "const": "supplemental_charge", "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "event_type": { "const": "receivable_created", "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "charge_amount": { "const": "0.000000", "type": "string" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "event_type": { "const": "receivable_payment", "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "charge_amount": { "const": "0.000000", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "event_type": { "const": "receivable_reduced", "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "charge_amount": { "const": "0.000000", "type": "string" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "event_type": { "const": "refund_posted", "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "charge_amount": { "const": "0.000000", "type": "string" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" } } } }, { "if": { "properties": { "event_type": { "const": "charge_waived", "type": "string" } }, "required": [ "event_type" ] }, "then": { "properties": { "adjustment_direction": { "type": "null" }, "amount": { "const": "0.000000", "type": "string" }, "charge_amount": { "const": "0.000000", "type": "string" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "funding_refund_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "adjustment_direction": { "const": "debit", "type": "string" }, "event_type": { "const": "manual_adjustment", "type": "string" } }, "required": [ "event_type", "adjustment_direction" ] }, "then": { "properties": { "funding_refund_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" }, "refund_amount": { "const": "0.000000", "type": "string" } } } }, { "if": { "properties": { "adjustment_direction": { "const": "credit", "type": "string" }, "event_type": { "const": "manual_adjustment", "type": "string" } }, "required": [ "event_type", "adjustment_direction" ] }, "then": { "properties": { "charge_amount": { "const": "0.000000", "type": "string" }, "collected_liability_amount": { "const": "0.000000", "type": "string" }, "funding_debit_amount": { "const": "0.000000", "type": "string" }, "receivable_amount": { "const": "0.000000", "type": "string" }, "receivable_direction": { "type": "null" } } } }, { "oneOf": [ { "properties": { "billing_component": { "const": "other", "type": "string" }, "component_detail_code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": "string" } }, "type": "object" }, { "properties": { "billing_component": { "enum": [ "generation_output", "reference_video", "reference_image", "reference_audio", "web_search" ], "type": "string" }, "component_detail_code": { "type": "null" } }, "type": "object" } ] }, { "oneOf": [ { "properties": { "event_type": { "const": "receivable_created", "type": "string" }, "receivable_direction": { "const": "increase", "type": "string" } }, "type": "object" }, { "properties": { "event_type": { "enum": [ "receivable_payment", "receivable_reduced" ], "type": "string" }, "receivable_direction": { "const": "decrease", "type": "string" } }, "type": "object" }, { "properties": { "event_type": { "enum": [ "hold_created", "hold_increased", "hold_reduced", "charge_captured", "supplemental_charge", "hold_released", "refund_posted", "charge_waived", "manual_adjustment" ], "type": "string" }, "receivable_direction": { "type": "null" } }, "type": "object" } ] } ], "description": "A permanent billing event. Creating, increasing, reducing or releasing a reservation does not by itself debit balance, issue a refund or change the amount due. Read the separate amount fields.", "properties": { "adjustment_direction": { "enum": [ "debit", "credit", null ], "type": [ "string", "null" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "audit_reason": { "maxLength": 1024, "minLength": 1, "type": [ "string", "null" ] }, "billing_component": { "$ref": "#/components/schemas/BillingComponent" }, "billing_correlation_id": { "$ref": "#/components/schemas/BillingCorrelationID" }, "billing_event_id": { "$ref": "#/components/schemas/StableID" }, "billing_operation_id": { "$ref": "#/components/schemas/StableID" }, "charge_amount": { "$ref": "#/components/schemas/Money" }, "collected_liability_amount": { "$ref": "#/components/schemas/Money" }, "component_detail_code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": [ "string", "null" ] }, "created_at": { "$ref": "#/components/schemas/UnixTime" }, "currency": { "const": "USD", "type": "string" }, "event_type": { "$ref": "#/components/schemas/BillingEventType" }, "funding_debit_amount": { "$ref": "#/components/schemas/Money" }, "funding_refund_amount": { "$ref": "#/components/schemas/Money" }, "quote_revision_after": { "minimum": 1, "type": "integer" }, "quote_revision_before": { "minimum": 0, "type": "integer" }, "receivable_amount": { "$ref": "#/components/schemas/Money" }, "receivable_direction": { "enum": [ "increase", "decrease", null ], "type": [ "string", "null" ] }, "refund_amount": { "$ref": "#/components/schemas/Money" }, "request_id": { "$ref": "#/components/schemas/RequestID" }, "reservation_revision_after": { "minimum": 1, "type": "integer" }, "reservation_revision_before": { "minimum": 0, "type": "integer" }, "settlement_status": { "$ref": "#/components/schemas/SettlementStatus" }, "task_id": { "$ref": "#/components/schemas/TaskID" } }, "required": [ "billing_event_id", "task_id", "request_id", "billing_correlation_id", "event_type", "billing_component", "amount", "charge_amount", "refund_amount", "collected_liability_amount", "funding_debit_amount", "funding_refund_amount", "receivable_amount", "receivable_direction", "adjustment_direction", "audit_reason", "component_detail_code", "currency", "settlement_status", "created_at" ], "type": "object" }, "BillingEventType": { "description": "Kinds of billing events", "enum": [ "hold_created", "hold_increased", "hold_reduced", "charge_captured", "supplemental_charge", "receivable_created", "receivable_payment", "receivable_reduced", "hold_released", "refund_posted", "charge_waived", "manual_adjustment" ], "type": "string" }, "CallbackEventBody": { "additionalProperties": false, "description": "The signed notification body. Its event ID and original bytes stay unchanged across retries.", "properties": { "created_at": { "minimum": 0, "type": "integer" }, "data": { "$ref": "#/components/schemas/CallbackEventData" }, "event_id": { "$ref": "#/components/schemas/UUID" }, "object": { "const": "event", "type": "string" }, "schema_version": { "const": 1, "type": "integer" }, "type": { "enum": [ "task.completed", "task.billing_settled" ], "type": "string" } }, "required": [ "event_id", "object", "type", "schema_version", "created_at", "data" ], "type": "object" }, "CallbackEventData": { "additionalProperties": false, "description": "Task status and billing fields from the same projection used by task queries. Download links are omitted.", "properties": { "billing_correlation_id": { "$ref": "#/components/schemas/StableID" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatus" }, "error": { "oneOf": [ { "$ref": "#/components/schemas/TaskError" }, { "type": "null" } ] }, "final_actual_cost": { "$ref": "#/components/schemas/NullableMoney" }, "model": { "$ref": "#/components/schemas/VideoModel" }, "request_id": { "$ref": "#/components/schemas/StableID" }, "settlement_status": { "$ref": "#/components/schemas/SettlementStatus" }, "status": { "enum": [ "succeeded", "failed", "cancelled" ], "type": "string" }, "task_id": { "$ref": "#/components/schemas/StableID" } }, "required": [ "task_id", "request_id", "billing_correlation_id", "model", "status", "delivery_status", "error", "settlement_status", "final_actual_cost" ], "type": "object" }, "CancelVideoTaskResponse": { "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "cancel_status": { "const": "requested", "type": "string" }, "reason_code": { "type": "null" } }, "type": "object" }, { "properties": { "cancel_status": { "const": "effective", "type": "string" }, "reason_code": { "type": "null" }, "task_status_at_response": { "const": "cancelled", "type": "string" } }, "type": "object" }, { "properties": { "cancel_status": { "enum": [ "not_effective", "failed" ], "type": "string" }, "reason_code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": "string" } }, "type": "object" } ] }, { "if": { "properties": { "task_status_at_response": { "const": "cancelled", "type": "string" } }, "required": [ "task_status_at_response" ] }, "then": { "properties": { "cancel_status": { "const": "effective", "type": "string" } } } } ], "description": "Cancellation response. Returns effective or not_effective. When cancellation takes effect, the task status is cancelled and the reason code is null. Otherwise, the reason code is generation_already_started.", "properties": { "cancel_operation_id": { "$ref": "#/components/schemas/StableID" }, "cancel_status": { "enum": [ "requested", "effective", "not_effective", "failed" ], "type": "string" }, "reason_code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": [ "string", "null" ] }, "task_id": { "$ref": "#/components/schemas/TaskID" }, "task_status_at_response": { "$ref": "#/components/schemas/TaskStatus" } }, "required": [ "task_id", "cancel_operation_id", "cancel_status", "task_status_at_response", "reason_code" ], "type": "object" }, "CancellationProjection": { "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "reason_code": { "type": "null" }, "status": { "enum": [ "requested", "effective" ], "type": "string" } }, "type": "object" }, { "properties": { "reason_code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": "string" }, "status": { "enum": [ "not_effective", "failed" ], "type": "string" } }, "type": "object" } ] } ], "description": "Cancellation information attached to a task", "properties": { "cancel_operation_id": { "$ref": "#/components/schemas/StableID" }, "reason_code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": [ "string", "null" ] }, "status": { "enum": [ "requested", "effective", "not_effective", "failed" ], "type": "string" } }, "required": [ "cancel_operation_id", "status", "reason_code" ], "type": "object" }, "CreateAssetRequest": { "additionalProperties": false, "description": "Fields for registering an asset", "properties": { "media_type": { "enum": [ "image", "audio", "video" ], "type": "string" }, "model": { "$ref": "#/components/schemas/AssetIntakeModel" }, "name": { "maxLength": 64, "minLength": 1, "not": { "pattern": "[\\u0000-\\u001F\\u007F-\\u009F\\u2028-\\u202E\\u2066-\\u2069]" }, "type": "string" }, "url": { "format": "uri", "maxLength": 2048, "minLength": 9, "pattern": "^https://", "type": "string" } }, "required": [ "url", "media_type", "model" ], "type": "object" }, "CreateAssetResponse": { "additionalProperties": false, "description": "Response when asset registration is accepted", "properties": { "asset_id": { "$ref": "#/components/schemas/AssetID" }, "status": { "const": "processing", "type": "string" } }, "required": [ "asset_id", "status" ], "type": "object" }, "CreateVideoGenerationRequest": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "model": { "enum": [ "dreamina-seedance-2-0-fast-260128", "dreamina-seedance-2-0-mini-260615" ] } } }, "then": { "properties": { "resolution": { "enum": [ "480p", "720p" ] } } } }, { "not": { "anyOf": [ { "required": [ "draft" ] }, { "required": [ "output_format" ] }, { "required": [ "omni_reference_task_type" ] }, { "required": [ "execution_expires_after" ] }, { "required": [ "priority" ] }, { "required": [ "safety_identifier" ] } ] }, "properties": { "content": { "items": {}, "maxItems": 16 }, "duration": { "default": 5, "maximum": 15, "minimum": 4 }, "generate_audio": { "default": false }, "ratio": { "default": "adaptive" }, "resolution": { "default": "720p" }, "seed": { "default": -1 } } }, { "if": { "properties": { "content": { "contains": { "not": { "required": [ "role" ] }, "properties": { "type": { "const": "image_url" } }, "required": [ "type" ] } } } }, "then": { "properties": { "content": { "contains": { "properties": { "type": { "enum": [ "image_url", "video_url", "audio_url" ] } }, "required": [ "type" ] }, "maxContains": 1, "minContains": 1 }, "model": { "enum": [ "dreamina-seedance-2-0-260128", "dreamina-seedance-2-0-fast-260128", "dreamina-seedance-2-0-mini-260615" ] } } } } ], "description": "A video generation request: the model, the input content and the output parameters. Fields not listed here are rejected.", "properties": { "callback_url": { "maxLength": 2048, "minLength": 1, "pattern": "^https://", "type": "string" }, "content": { "allOf": [ { "contains": { "properties": { "role": { "const": "first_frame" }, "type": { "const": "image_url" } }, "required": [ "type", "role" ], "type": "object" }, "maxContains": 1, "minContains": 0 }, { "contains": { "properties": { "role": { "const": "last_frame" }, "type": { "const": "image_url" } }, "required": [ "type", "role" ], "type": "object" }, "maxContains": 1, "minContains": 0 } ], "items": { "oneOf": [ { "$ref": "#/components/schemas/VideoTextContent" }, { "$ref": "#/components/schemas/VideoImageContent" }, { "$ref": "#/components/schemas/VideoVideoContent" }, { "$ref": "#/components/schemas/VideoAudioContent" } ] }, "maxItems": 51, "minItems": 1, "type": "array" }, "draft": { "type": "boolean" }, "duration": { "type": "integer" }, "execution_expires_after": { "maximum": 259200, "minimum": 3600, "type": "integer" }, "generate_audio": { "type": "boolean" }, "model": { "$ref": "#/components/schemas/VideoModel" }, "omni_reference_task_type": { "enum": [ "auto", "reference", "edit", "extend" ], "type": "string" }, "output_format": { "enum": [ "mp4", "mov" ], "type": "string" }, "priority": { "maximum": 9, "minimum": 0, "type": "integer" }, "ratio": { "enum": [ "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16" ], "type": "string" }, "resolution": { "enum": [ "480p", "720p", "1080p" ], "type": "string" }, "return_last_frame": { "default": false, "type": "boolean" }, "safety_identifier": { "maxLength": 64, "type": "string" }, "seed": { "maximum": 4294967295, "minimum": -1, "type": "integer" }, "watermark": { "default": false, "type": "boolean" } }, "required": [ "model", "content" ], "type": "object" }, "CreateVideoGenerationResponse": { "additionalProperties": false, "description": "Response when a video task is accepted", "properties": { "billing_correlation_id": { "$ref": "#/components/schemas/BillingCorrelationID" }, "created_at": { "$ref": "#/components/schemas/UnixTime" }, "id": { "$ref": "#/components/schemas/TaskID" }, "model": { "$ref": "#/components/schemas/VideoModel" }, "object": { "const": "video.task", "type": "string" }, "phase": { "const": "preparing_assets", "type": "string" }, "quote": { "$ref": "#/components/schemas/VideoQuote" }, "request_id": { "$ref": "#/components/schemas/RequestID" }, "settlement_status": { "const": "reserved", "type": "string" }, "status": { "const": "queued", "type": "string" } }, "required": [ "id", "object", "request_id", "billing_correlation_id", "model", "status", "settlement_status", "quote", "created_at" ], "type": "object" }, "DeliveryStatus": { "description": "States of result delivery", "enum": [ "pending", "materializing", "available", "output_unavailable" ], "type": "string" }, "Error": { "additionalProperties": false, "description": "Fields describing a request error", "properties": { "code": { "maxLength": 96, "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$", "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ErrorEnvelope": { "additionalProperties": false, "description": "The standard error response shape", "properties": { "error": { "$ref": "#/components/schemas/Error" }, "trace_id": { "$ref": "#/components/schemas/TraceID" } }, "required": [ "error", "trace_id" ], "type": "object" }, "InlineAudioData": { "additionalProperties": false, "description": "An inline base64 audio clip.", "properties": { "url": { "maxLength": 20000024, "pattern": "^data:audio/(wav|mpeg|mp3|x-wav);base64,[A-Za-z0-9+/]+={0,2}$", "type": "string" } }, "required": [ "url" ], "type": "object" }, "InlineMediaData": { "additionalProperties": false, "description": "An inline base64 image.", "properties": { "url": { "maxLength": 40000023, "pattern": "^data:image/(jpeg|png|webp);base64,[A-Za-z0-9+/]+={0,2}$", "type": "string" } }, "required": [ "url" ], "type": "object" }, "InsufficientBalanceDetails": { "additionalProperties": false, "description": "Reservation quote included when balance is insufficient", "properties": { "currency": { "const": "USD", "type": "string" }, "estimated_usage_upper_bound": { "$ref": "#/components/schemas/UsageUpperBound" }, "meter_type": { "const": "seedance_video_generation", "type": "string" }, "price_version": { "$ref": "#/components/schemas/StableID" }, "reserved_amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "currency", "reserved_amount", "meter_type", "estimated_usage_upper_bound", "price_version" ], "type": "object" }, "MediaSourceURL": { "additionalProperties": false, "description": "A public HTTPS image source that the platform downloads before generation.", "properties": { "url": { "maxLength": 2048, "minLength": 1, "pattern": "^https://", "type": "string" } }, "required": [ "url" ], "type": "object" }, "Money": { "description": "Non-negative USD amount written as a string with six decimal places.", "example": "0.361564", "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$", "type": "string" }, "NullableMoney": { "description": "USD amount as a six-decimal string, or null.", "example": null, "pattern": "^(0|[1-9][0-9]*)\\.[0-9]{6}$", "type": [ "string", "null" ] }, "NullableUnixTime": { "description": "Whole Unix seconds, or null", "minimum": 0, "type": [ "integer", "null" ] }, "PlatformAssetReference": { "additionalProperties": false, "description": "Reference to a platform asset using asset:// followed by its ID.", "properties": { "url": { "maxLength": 128, "minLength": 12, "pattern": "^asset://ast-[0-9A-Za-z][0-9A-Za-z-]{3,111}$", "type": "string" } }, "required": [ "url" ], "type": "object" }, "ReconciliationSummary": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "reason_code": { "const": "missing_billable_usage", "type": "string" } }, "required": [ "reason_code" ] }, "then": { "properties": { "missing_meters": { "minItems": 1, "type": "array", "uniqueItems": true } } } } ], "description": "Summary of usage verification", "properties": { "case_id": { "$ref": "#/components/schemas/StableID" }, "customer_action_required": { "type": "boolean" }, "missing_meters": { "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 16, "type": "array", "uniqueItems": true }, "reason_code": { "enum": [ "missing_billable_usage", "usage_schema_drift", "unknown_usage_unit", "price_rule_not_unique", "output_unavailable" ], "type": "string" } }, "required": [ "case_id", "reason_code", "missing_meters", "customer_action_required" ], "type": "object" }, "RequestID": { "$ref": "#/components/schemas/StableID", "description": "You may supply a Request ID. Invalid or reused values are replaced. The response carries the bounded ID selected for this request." }, "SHA256": { "description": "SHA-256 digest of the stored asset bytes", "maxLength": 64, "minLength": 64, "not": { "const": "0000000000000000000000000000000000000000000000000000000000000000" }, "pattern": "^[0-9a-f]{64}$", "type": "string" }, "SeedanceUsage": { "additionalProperties": false, "description": "Actual usage recorded for video generation", "properties": { "fps": { "maximum": 120, "minimum": 1, "type": "integer" }, "has_reference_video": { "type": "boolean" }, "input_video_duration_seconds": { "minimum": 0, "type": "integer" }, "meter_type": { "const": "seedance_video_generation", "type": "string" }, "output_duration_seconds": { "minimum": 0, "type": "integer" }, "resolution": { "enum": [ "480p", "720p", "1080p" ], "type": "string" }, "video_tokens": { "minimum": 0, "type": [ "integer", "null" ] } }, "required": [ "meter_type", "video_tokens", "output_duration_seconds", "input_video_duration_seconds", "resolution", "fps", "has_reference_video" ], "type": "object" }, "SettlementStatus": { "description": "States of billing settlement", "enum": [ "reserved", "pending", "reconciliation_required", "settled", "settled_with_receivable" ], "type": "string" }, "StableID": { "description": "A stable object ID", "maxLength": 128, "minLength": 4, "pattern": "^[A-Za-z][0-9A-Za-z_-]*$", "type": "string" }, "TaskBillingSummary": { "additionalProperties": false, "description": "A task's billing summary", "properties": { "billing_url": { "format": "uri-reference", "pattern": "^/v1/video/tasks/[A-Za-z][0-9A-Za-z_-]*/billing$", "type": "string" }, "collected_liability_amount": { "$ref": "#/components/schemas/Money" }, "currency": { "const": "USD", "type": "string" }, "final_actual_cost": { "$ref": "#/components/schemas/NullableMoney" }, "funding_debit_amount": { "$ref": "#/components/schemas/Money" }, "funding_refund_amount": { "$ref": "#/components/schemas/Money" }, "outstanding_receivable": { "$ref": "#/components/schemas/Money" }, "refunded_liability_amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "currency", "final_actual_cost", "collected_liability_amount", "funding_debit_amount", "refunded_liability_amount", "funding_refund_amount", "outstanding_receivable", "billing_url" ], "type": "object" }, "TaskError": { "additionalProperties": false, "description": "Error information attached to a task", "properties": { "code": { "enum": [ "no_common_asset_route", "asset_not_ready", "asset_review_timeout", "route_misconfigured", "route_temporarily_unavailable", "generation_expired", "generation_failed", "input_fetch_failed", "input_url_not_allowed", "input_too_large", "input_unsupported", "input_rejected", "input_preparation_failed", "input_duration_exceeded" ], "type": "string" }, "details": { "additionalProperties": true, "properties": { "content_index": { "maximum": 50, "minimum": 0, "type": "integer" } }, "type": "object" }, "message": { "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "TaskID": { "$ref": "#/components/schemas/StableID", "description": "Platform ID for a video task" }, "TaskLocation": { "description": "Relative path for reading a task", "example": "/v1/video/tasks/task_example_0001", "format": "uri-reference", "maxLength": 160, "minLength": 20, "pattern": "^/v1/video/tasks/[A-Za-z][0-9A-Za-z_-]*$", "type": "string" }, "TaskPhase": { "description": "Phases of task execution", "enum": [ "preparing_assets", "waiting_route", "submitting", "provider_processing", "reconciling", "finalizing", "settlement_pending", null ], "type": [ "string", "null" ] }, "TaskStatus": { "description": "Execution states of a video task", "enum": [ "queued", "processing", "succeeded", "failed", "cancelled" ], "type": "string" }, "TraceID": { "$ref": "#/components/schemas/StableID", "description": "Trace ID for investigating an error" }, "UUID": { "description": "A unique event ID in UUID format.", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "UnixTime": { "description": "Whole seconds measured from the Unix epoch", "minimum": 0, "type": "integer" }, "UsageUpperBound": { "additionalProperties": false, "description": "Upper estimate used when reserving funds", "properties": { "video_tokens": { "minimum": 1, "type": "integer" } }, "required": [ "video_tokens" ], "type": "object" }, "VideoAudioContent": { "additionalProperties": false, "description": "Reference audio accepts an HTTPS URL or a platform asset reference. Each item lasts 2–15 seconds and the total is at most 15 seconds. Audio requires a reference image or video. URL audio is checked during preparation; an excessive total fails with input_duration_exceeded, releases the full reservation and incurs zero charge. Registered assets are checked at creation.", "properties": { "audio_url": { "oneOf": [ { "$ref": "#/components/schemas/PlatformAssetReference" }, { "$ref": "#/components/schemas/MediaSourceURL" }, { "$ref": "#/components/schemas/InlineAudioData" } ] }, "role": { "const": "reference_audio", "type": "string" }, "type": { "const": "audio_url", "type": "string" } }, "required": [ "type", "role", "audio_url" ], "type": "object" }, "VideoImageContent": { "additionalProperties": false, "description": "An image item in the task input", "properties": { "image_url": { "oneOf": [ { "$ref": "#/components/schemas/PlatformAssetReference" }, { "$ref": "#/components/schemas/MediaSourceURL" }, { "$ref": "#/components/schemas/InlineMediaData" } ] }, "role": { "enum": [ "reference_image", "first_frame", "last_frame" ], "type": "string" }, "type": { "const": "image_url", "type": "string" } }, "required": [ "type", "image_url" ], "type": "object" }, "VideoModel": { "description": "Public model IDs accepted for video tasks", "enum": [ "dreamina-seedance-2-0-260128", "dreamina-seedance-2-0-fast-260128", "dreamina-seedance-2-0-mini-260615" ], "type": "string" }, "VideoOutput": { "additionalProperties": false, "description": "Collection of generated result files", "properties": { "assets": { "items": { "$ref": "#/components/schemas/VideoOutputAsset" }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [ "assets" ], "type": "object" }, "VideoOutputAsset": { "allOf": [ { "additionalProperties": false, "properties": { "asset_id": { "$ref": "#/components/schemas/StableID" }, "delivery_source": { "enum": [ "platform" ], "type": "string" }, "download_status": {}, "expires_at": { "$ref": "#/components/schemas/NullableUnixTime" }, "materialization_status": { "enum": [ "completed", "retrying", "failed" ], "type": "string" }, "materialized_at": { "$ref": "#/components/schemas/NullableUnixTime" }, "media_type": { "enum": [ "video", "image", "audio" ], "type": "string" }, "role": { "enum": [ "result", "last_frame", "audio" ], "type": "string" }, "url": {} }, "required": [ "asset_id", "media_type", "role", "url", "materialized_at", "expires_at", "delivery_source", "materialization_status", "download_status" ], "type": "object" }, { "oneOf": [ { "properties": { "download_status": { "const": "available", "type": "string" }, "url": { "format": "uri", "maxLength": 4096, "minLength": 12, "pattern": "^https://", "type": "string" } }, "required": [ "url", "download_status" ], "type": "object" }, { "properties": { "download_status": { "const": "expired", "type": "string" }, "expires_at": { "$ref": "#/components/schemas/UnixTime" }, "url": { "type": "null" } }, "required": [ "url", "expires_at", "download_status" ], "type": "object" }, { "properties": { "download_status": { "const": "unavailable", "type": "string" }, "url": { "type": "null" } }, "required": [ "url", "download_status" ], "type": "object" } ] }, { "allOf": [ { "properties": { "delivery_source": { "const": "platform", "type": "string" }, "expires_at": { "$ref": "#/components/schemas/UnixTime" }, "materialization_status": { "const": "completed", "type": "string" }, "materialized_at": { "$ref": "#/components/schemas/UnixTime" } }, "required": [ "delivery_source", "materialized_at", "expires_at", "materialization_status" ], "type": "object" } ] } ], "description": "A result file with an HTTPS link when downloadable. The link is null when expired or unavailable. Retention starts when the result is ready and is tracked separately from task completion." }, "VideoQuote": { "additionalProperties": false, "description": "Quote for the funds reserved at task acceptance", "properties": { "currency": { "const": "USD", "type": "string" }, "estimated_usage_upper_bound": { "$ref": "#/components/schemas/UsageUpperBound" }, "meter_type": { "const": "seedance_video_generation", "type": "string" }, "price_version": { "$ref": "#/components/schemas/StableID" }, "quote_policy_version": { "maxLength": 128, "minLength": 1, "pattern": "^[0-9A-Za-z][0-9A-Za-z._:-]*$", "type": "string" }, "reserved_amount": { "$ref": "#/components/schemas/Money" } }, "required": [ "currency", "reserved_amount", "meter_type", "estimated_usage_upper_bound", "price_version", "quote_policy_version" ], "type": "object" }, "VideoTask": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "usage": { "properties": { "video_tokens": { "type": "null" } }, "required": [ "video_tokens" ], "type": "object" } }, "required": [ "usage" ] }, "then": { "properties": { "settlement_status": { "const": "reconciliation_required", "type": "string" } } } }, { "if": { "properties": { "settlement_status": { "enum": [ "settled", "settled_with_receivable" ], "type": "string" }, "status": { "const": "succeeded", "type": "string" } }, "required": [ "status", "settlement_status" ] }, "then": { "properties": { "usage": { "allOf": [ { "$ref": "#/components/schemas/SeedanceUsage" }, { "properties": { "video_tokens": { "minimum": 0, "type": "integer" } }, "type": "object" } ] } } } }, { "if": { "properties": { "status": { "const": "succeeded", "type": "string" } }, "required": [ "status" ] }, "then": { "properties": { "delivery_status": { "enum": [ "available" ], "type": "string" }, "output": { "allOf": [ { "$ref": "#/components/schemas/VideoOutput" }, { "properties": { "assets": { "contains": { "properties": { "role": { "const": "result", "type": "string" } }, "required": [ "role" ], "type": "object" }, "minContains": 1, "minItems": 1, "type": "array" } }, "required": [ "assets" ], "type": "object" } ] } } } }, { "if": { "properties": { "status": { "const": "cancelled", "type": "string" } }, "required": [ "status" ] }, "then": { "properties": { "cancellation": { "allOf": [ { "$ref": "#/components/schemas/CancellationProjection" }, { "properties": { "status": { "const": "effective", "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "cancellation": { "properties": { "status": { "const": "effective", "type": "string" } }, "required": [ "status" ], "type": "object" } }, "required": [ "cancellation" ] }, "then": { "properties": { "status": { "const": "cancelled", "type": "string" } } } }, { "if": { "properties": { "settlement_status": { "const": "reconciliation_required", "type": "string" } }, "required": [ "settlement_status" ] }, "then": { "properties": { "billing": { "allOf": [ { "$ref": "#/components/schemas/TaskBillingSummary" }, { "properties": { "final_actual_cost": { "type": "null" } }, "type": "object" } ] } } } }, { "if": { "properties": { "settlement_status": { "enum": [ "settled", "settled_with_receivable" ], "type": "string" } }, "required": [ "settlement_status" ] }, "then": { "properties": { "billing": { "allOf": [ { "$ref": "#/components/schemas/TaskBillingSummary" }, { "properties": { "final_actual_cost": { "$ref": "#/components/schemas/Money" } }, "type": "object" } ] } } } }, { "if": { "properties": { "settlement_status": { "enum": [ "reserved", "pending" ], "type": "string" } }, "required": [ "settlement_status" ] }, "then": { "properties": { "billing": { "allOf": [ { "$ref": "#/components/schemas/TaskBillingSummary" }, { "properties": { "final_actual_cost": { "type": "null" } }, "type": "object" } ] } } } }, { "if": { "properties": { "status": { "enum": [ "queued", "processing" ], "type": "string" } }, "required": [ "status" ] }, "then": { "properties": { "billing": { "allOf": [ { "$ref": "#/components/schemas/TaskBillingSummary" }, { "properties": { "final_actual_cost": { "type": "null" } }, "type": "object" } ] } } } }, { "if": { "properties": { "status": { "enum": [ "failed", "cancelled" ], "type": "string" } }, "required": [ "status" ] }, "then": { "properties": { "settlement_status": { "enum": [ "pending", "settled" ], "type": "string" } } } }, { "if": { "properties": { "settlement_status": { "const": "settled", "type": "string" }, "status": { "enum": [ "failed", "cancelled" ], "type": "string" } }, "required": [ "status", "settlement_status" ] }, "then": { "properties": { "billing": { "allOf": [ { "$ref": "#/components/schemas/TaskBillingSummary" }, { "properties": { "final_actual_cost": { "const": "0.000000", "type": "string" }, "outstanding_receivable": { "const": "0.000000", "type": "string" } }, "type": "object" } ] } } } }, { "if": { "properties": { "delivery_status": { "const": "output_unavailable", "type": "string" } }, "required": [ "delivery_status" ] }, "then": { "properties": { "billing": { "allOf": [ { "$ref": "#/components/schemas/TaskBillingSummary" }, { "properties": { "final_actual_cost": { "type": "null" } }, "type": "object" } ] }, "settlement_status": { "const": "reconciliation_required", "type": "string" }, "status": { "const": "processing", "type": "string" } } } } ], "description": "Detailed task view. With an unavailable result, the task stays processing and settlement remains under review. Succeeded tasks have result files and available delivery. Failed or cancelled tasks can have pending or settled billing; once settled, their final charge and amount due are zero.", "properties": { "billing": { "$ref": "#/components/schemas/TaskBillingSummary" }, "billing_correlation_id": { "$ref": "#/components/schemas/BillingCorrelationID" }, "cancellation": { "oneOf": [ { "$ref": "#/components/schemas/CancellationProjection" }, { "type": "null" } ] }, "completed_at": { "$ref": "#/components/schemas/NullableUnixTime" }, "created_at": { "$ref": "#/components/schemas/UnixTime" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatus" }, "error": { "oneOf": [ { "$ref": "#/components/schemas/TaskError" }, { "type": "null" } ] }, "id": { "$ref": "#/components/schemas/TaskID" }, "model": { "$ref": "#/components/schemas/VideoModel" }, "object": { "const": "video.task", "type": "string" }, "output": { "oneOf": [ { "$ref": "#/components/schemas/VideoOutput" }, { "type": "null" } ] }, "phase": { "$ref": "#/components/schemas/TaskPhase" }, "request_id": { "$ref": "#/components/schemas/RequestID" }, "settlement_status": { "$ref": "#/components/schemas/SettlementStatus" }, "started_at": { "$ref": "#/components/schemas/NullableUnixTime" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "usage": { "oneOf": [ { "$ref": "#/components/schemas/SeedanceUsage" }, { "type": "null" } ] } }, "required": [ "id", "object", "request_id", "billing_correlation_id", "model", "status", "phase", "delivery_status", "settlement_status", "created_at", "started_at", "completed_at", "usage", "billing", "output", "cancellation", "error" ], "type": "object" }, "VideoTaskBilling": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "settlement_status": { "const": "reconciliation_required", "type": "string" } }, "required": [ "settlement_status" ] }, "then": { "properties": { "final_actual_cost": { "type": "null" }, "reconciliation": { "$ref": "#/components/schemas/ReconciliationSummary" } } } }, { "if": { "properties": { "settlement_status": { "enum": [ "settled", "settled_with_receivable" ], "type": "string" } }, "required": [ "settlement_status" ] }, "then": { "properties": { "final_actual_cost": { "$ref": "#/components/schemas/Money" }, "reconciliation": { "type": "null" } } } }, { "if": { "properties": { "settlement_status": { "enum": [ "reserved", "pending" ], "type": "string" } }, "required": [ "settlement_status" ] }, "then": { "properties": { "final_actual_cost": { "type": "null" }, "reconciliation": { "type": "null" } } } }, { "if": { "properties": { "task_status": { "enum": [ "queued", "processing" ], "type": "string" } }, "required": [ "task_status" ] }, "then": { "properties": { "final_actual_cost": { "type": "null" } } } }, { "if": { "properties": { "task_status": { "enum": [ "failed", "cancelled" ], "type": "string" } }, "required": [ "task_status" ] }, "then": { "properties": { "settlement_status": { "enum": [ "pending", "settled" ], "type": "string" } } } }, { "if": { "properties": { "settlement_status": { "const": "settled", "type": "string" }, "task_status": { "enum": [ "failed", "cancelled" ], "type": "string" } }, "required": [ "task_status", "settlement_status" ] }, "then": { "properties": { "final_actual_cost": { "const": "0.000000", "type": "string" }, "outstanding_receivable": { "const": "0.000000", "type": "string" }, "reconciliation": { "type": "null" } } } } ], "description": "Task billing summary and event pagination", "properties": { "billing_correlation_id": { "$ref": "#/components/schemas/BillingCorrelationID" }, "charged_amount": { "$ref": "#/components/schemas/Money" }, "collected_liability_amount": { "$ref": "#/components/schemas/Money" }, "currency": { "const": "USD", "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/BillingEvent" }, "maxItems": 100, "type": "array" }, "final_actual_cost": { "$ref": "#/components/schemas/NullableMoney" }, "funding_debit_amount": { "$ref": "#/components/schemas/Money" }, "funding_refund_amount": { "$ref": "#/components/schemas/Money" }, "model": { "$ref": "#/components/schemas/VideoModel" }, "next_cursor": { "maxLength": 256, "minLength": 1, "type": [ "string", "null" ] }, "object": { "const": "video.task.billing", "type": "string" }, "outstanding_receivable": { "$ref": "#/components/schemas/Money" }, "reconciliation": { "oneOf": [ { "$ref": "#/components/schemas/ReconciliationSummary" }, { "type": "null" } ] }, "refunded_liability_amount": { "$ref": "#/components/schemas/Money" }, "request_id": { "$ref": "#/components/schemas/RequestID" }, "reserved_amount": { "$ref": "#/components/schemas/Money" }, "settlement_status": { "$ref": "#/components/schemas/SettlementStatus" }, "task_id": { "$ref": "#/components/schemas/TaskID" }, "task_status": { "$ref": "#/components/schemas/TaskStatus" } }, "required": [ "object", "task_id", "request_id", "billing_correlation_id", "model", "task_status", "settlement_status", "currency", "reserved_amount", "charged_amount", "collected_liability_amount", "funding_debit_amount", "refunded_liability_amount", "funding_refund_amount", "outstanding_receivable", "final_actual_cost", "events", "next_cursor", "reconciliation" ], "type": "object" }, "VideoTaskList": { "additionalProperties": false, "description": "A team task page contains at most page_size items. The last page has a null next_cursor. Other pages are full, and their cursor continues after the last item.", "properties": { "data": { "items": { "$ref": "#/components/schemas/VideoTaskSummary" }, "maxItems": 100, "type": "array" }, "next_cursor": { "maxLength": 256, "minLength": 1, "type": [ "string", "null" ] }, "object": { "const": "list", "type": "string" } }, "required": [ "object", "data", "next_cursor" ], "type": "object" }, "VideoTaskSummary": { "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "const": "succeeded", "type": "string" } }, "required": [ "status" ] }, "then": { "properties": { "delivery_status": { "enum": [ "available" ], "type": "string" } } } }, { "if": { "properties": { "status": { "enum": [ "failed", "cancelled" ], "type": "string" } }, "required": [ "status" ] }, "then": { "properties": { "settlement_status": { "enum": [ "pending", "settled" ], "type": "string" } } } }, { "if": { "properties": { "delivery_status": { "const": "output_unavailable", "type": "string" } }, "required": [ "delivery_status" ] }, "then": { "properties": { "settlement_status": { "const": "reconciliation_required", "type": "string" }, "status": { "const": "processing", "type": "string" } } } } ], "description": "Summary of a task in a list", "properties": { "billing_correlation_id": { "$ref": "#/components/schemas/BillingCorrelationID" }, "cancellation": { "oneOf": [ { "$ref": "#/components/schemas/CancellationProjection" }, { "type": "null" } ] }, "completed_at": { "$ref": "#/components/schemas/NullableUnixTime" }, "created_at": { "$ref": "#/components/schemas/UnixTime" }, "delivery_status": { "$ref": "#/components/schemas/DeliveryStatus" }, "id": { "$ref": "#/components/schemas/TaskID" }, "model": { "$ref": "#/components/schemas/VideoModel" }, "phase": { "$ref": "#/components/schemas/TaskPhase" }, "request_id": { "$ref": "#/components/schemas/RequestID" }, "settlement_status": { "$ref": "#/components/schemas/SettlementStatus" }, "started_at": { "$ref": "#/components/schemas/NullableUnixTime" }, "status": { "$ref": "#/components/schemas/TaskStatus" } }, "required": [ "id", "request_id", "billing_correlation_id", "model", "status", "phase", "delivery_status", "settlement_status", "created_at", "started_at", "completed_at" ], "type": "object" }, "VideoTextContent": { "additionalProperties": false, "description": "A text item in the task input", "properties": { "text": { "maxLength": 10000, "minLength": 1, "type": "string" }, "type": { "const": "text", "type": "string" } }, "required": [ "type", "text" ], "type": "object" }, "VideoVideoContent": { "additionalProperties": false, "description": "A reference video can be an HTTPS URL or a platform asset reference. Each item lasts 2–15 seconds and the total is at most 15 seconds. URL videos reserve 15 input seconds at the resolution’s maximum area and the with-video price. Preparation checks the actual durations; an excess fails with input_duration_exceeded, releases the full reservation and incurs zero charge. Registered assets are checked at creation. Video data URIs are not accepted.", "properties": { "role": { "const": "reference_video", "type": "string" }, "type": { "const": "video_url", "type": "string" }, "video_url": { "oneOf": [ { "$ref": "#/components/schemas/PlatformAssetReference" }, { "$ref": "#/components/schemas/MediaSourceURL" } ] } }, "required": [ "type", "role", "video_url" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "scheme": "bearer", "type": "http" } } }, "info": { "title": "Chenvoya API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/assets": { "post": { "description": "Requires service.use. Register an image, audio clip or video at a public HTTPS address. After acceptance, the file is fetched and checked asynchronously. Idempotency belongs to your team and this operation: the same request returns the saved response; a different request with the same value is rejected. Models without asset input support return invalid_request without creating an asset, intake job or reservation.", "operationId": "createAsset", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "example": { "media_type": "image", "model": "dreamina-seedance-2-0-260128", "name": "reference", "url": "https://images.example.test/reference.png" }, "schema": { "$ref": "#/components/schemas/CreateAssetRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "asset_id": "ast-11111111111111111111111111111111", "status": "processing" }, "schema": { "$ref": "#/components/schemas/CreateAssetResponse" } } }, "description": "Asset intake was accepted. Follow Location to check its progress.", "headers": { "Cache-Control": { "required": true, "schema": { "const": "no-store", "type": "string" } }, "Location": { "required": true, "schema": { "$ref": "#/components/schemas/AssetLocation" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/AssetBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/AssetPermissionDeniedResponse" }, "409": { "$ref": "#/components/responses/AssetIdempotencyConflictResponse" }, "410": { "$ref": "#/components/responses/AssetReplayExpiredResponse" }, "429": { "$ref": "#/components/responses/AssetIntakeLimitResponse" }, "503": { "$ref": "#/components/responses/DependencyUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "Register an asset", "tags": [ "Assets" ] } }, "/v1/assets/{asset_id}": { "get": { "description": "Requires service.use and an asset owned by your team. Unknown IDs, deleted assets and assets owned by another team all return asset_not_found. Active assets include their size and digest, plus dimensions or duration where applicable. These measurements are omitted during processing or when unavailable. The original source address is never returned.", "operationId": "getAsset", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/AssetID" } ], "responses": { "200": { "content": { "application/json": { "examples": { "active": { "value": { "asset_id": "ast-11111111111111111111111111111111", "created_at": 1700000000, "height": 480, "media_type": "image", "model": "dreamina-seedance-2-0-260128", "object": "asset", "sha256": "1111111111111111111111111111111111111111111111111111111111111111", "size_bytes": 1024, "status": "active", "updated_at": 1700000100, "width": 640 } }, "processing": { "value": { "asset_id": "ast-11111111111111111111111111111111", "created_at": 1700000000, "media_type": "image", "model": "dreamina-seedance-2-0-260128", "name": "reference", "object": "asset", "status": "processing", "updated_at": 1700000100 } }, "unavailable": { "value": { "asset_id": "ast-11111111111111111111111111111111", "created_at": 1700000000, "failure_reason": "source_fetch_failed", "media_type": "image", "model": "dreamina-seedance-2-0-260128", "object": "asset", "status": "unavailable", "updated_at": 1700000100 } } }, "schema": { "$ref": "#/components/schemas/AssetReadResponse" } } }, "description": "The asset's current state and the metadata safe to return at that state.", "headers": { "Cache-Control": { "required": true, "schema": { "const": "no-store", "type": "string" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/AssetPermissionDeniedResponse" }, "404": { "$ref": "#/components/responses/AssetNotFoundResponse" }, "503": { "$ref": "#/components/responses/DependencyUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "Check an asset", "tags": [ "Assets" ] } }, "/v1/video/generations": { "post": { "description": "Submit a prompt with optional images, videos or audio to create an asynchronous generation task; the task ID and the reserved amount come back at once. HTTP 202 means the task was accepted; then read its progress and result by task ID. Images and audio may also be sent inline as base64, and the create body is limited to 64 MiB. A body over 2 MiB has a 120-second read deadline, and each team can send at most two at a time; more returns 429 rate_limited. One image may omit role to act as first_frame; omitting role among several images, or conflicting roles, is refused.", "operationId": "createVideoGeneration", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "examples": { "reviewed_image": { "value": { "content": [ { "text": "Animate the reviewed reference image.", "type": "text" }, { "image_url": { "url": "asset://ast-example-0001" }, "role": "reference_image", "type": "image_url" } ], "duration": 5, "model": "dreamina-seedance-2-0-260128", "ratio": "16:9", "resolution": "720p" } }, "text": { "value": { "content": [ { "text": "A paper boat crossing a moonlit lake.", "type": "text" } ], "model": "dreamina-seedance-2-0-260128" } } }, "schema": { "$ref": "#/components/schemas/CreateVideoGenerationRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "examples": { "adaptive_default": { "value": { "billing_correlation_id": "billcorr_example_0001", "created_at": 0, "id": "task_example_0001", "model": "dreamina-seedance-2-0-260128", "object": "video.task", "quote": { "currency": "USD", "estimated_usage_upper_bound": { "video_tokens": 111779 }, "meter_type": "seedance_video_generation", "price_version": "price_example_0001", "quote_policy_version": "seedance2_quote_v1", "reserved_amount": "0.782453" }, "request_id": "req_example_0001", "settlement_status": "reserved", "status": "queued" } }, "reviewed_image_16_9": { "value": { "billing_correlation_id": "billcorr_example_0002", "created_at": 0, "id": "task_example_0002", "model": "dreamina-seedance-2-0-260128", "object": "video.task", "quote": { "currency": "USD", "estimated_usage_upper_bound": { "video_tokens": 111078 }, "meter_type": "seedance_video_generation", "price_version": "price_example_0001", "quote_policy_version": "seedance2_quote_v1", "reserved_amount": "0.777546" }, "request_id": "req_example_0002", "settlement_status": "reserved", "status": "queued" } } }, "schema": { "$ref": "#/components/schemas/CreateVideoGenerationResponse" } } }, "description": "Accepted: the task is created and the funds are reserved. The Location response header is the task's lookup path.", "headers": { "Location": { "required": true, "schema": { "$ref": "#/components/schemas/TaskLocation" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/CreateVideoGenerationBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "409": { "$ref": "#/components/responses/IdempotencyConflictResponse" }, "429": { "$ref": "#/components/responses/RequestLimitResponse" }, "500": { "$ref": "#/components/responses/InternalErrorResponse" }, "503": { "$ref": "#/components/responses/FundingIntakeUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a video task", "tags": [ "Video" ] } }, "/v1/video/tasks": { "get": { "description": "Returns tasks across your team, including those created with other API keys. Newer tasks come first, with Task ID breaking ties. Teams with no tasks receive an empty list. List items contain IDs, model, status, timestamps and cancellation details when a cancellation exists. Fetch task details for usage, billing, result files and errors.", "operationId": "listVideoTasks", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/VideoTaskCursor" }, { "$ref": "#/components/parameters/VideoTaskPageSize" } ], "responses": { "200": { "content": { "application/json": { "example": { "data": [ { "billing_correlation_id": "billcorr_example_0001", "completed_at": 2, "created_at": 0, "delivery_status": "available", "id": "task_example_0001", "model": "dreamina-seedance-2-0-260128", "phase": null, "request_id": "req_example_0001", "settlement_status": "settled", "started_at": 1, "status": "succeeded" } ], "next_cursor": null, "object": "list" }, "schema": { "$ref": "#/components/schemas/VideoTaskList" } } }, "description": "One page of the current team's tasks.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "429": { "$ref": "#/components/responses/RateLimitResponse" }, "500": { "$ref": "#/components/responses/InternalErrorResponse" }, "503": { "$ref": "#/components/responses/DependencyUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "List team tasks", "tags": [ "Video" ] } }, "/v1/video/tasks/{task_id}": { "get": { "description": "Check execution progress, delivery, usage and the billing summary. Task status, delivery status and settlement status describe separate parts of the work. A download link is null once it expires or while the file is unavailable.", "operationId": "getVideoTask", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/TaskID" } ], "responses": { "200": { "content": { "application/json": { "example": { "billing": { "billing_url": "/v1/video/tasks/task_example_0001/billing", "collected_liability_amount": "0.361564", "currency": "USD", "final_actual_cost": "0.361564", "funding_debit_amount": "0.361564", "funding_refund_amount": "0.000000", "outstanding_receivable": "0.000000", "refunded_liability_amount": "0.000000" }, "billing_correlation_id": "billcorr_example_0001", "cancellation": null, "completed_at": 2, "created_at": 0, "delivery_status": "available", "error": null, "id": "task_example_0001", "model": "dreamina-seedance-2-0-260128", "object": "video.task", "output": { "assets": [ { "asset_id": "asset_example_0001", "delivery_source": "platform", "download_status": "available", "expires_at": 86405, "materialization_status": "completed", "materialized_at": 5, "media_type": "video", "role": "result", "url": "https://media.example.invalid/download/result-0001?signature=example" } ] }, "phase": null, "request_id": "req_example_0001", "settlement_status": "settled", "started_at": 1, "status": "succeeded", "usage": { "fps": 24, "has_reference_video": false, "input_video_duration_seconds": 0, "meter_type": "seedance_video_generation", "output_duration_seconds": 5, "resolution": "720p", "video_tokens": 51652 } }, "schema": { "$ref": "#/components/schemas/VideoTask" } } }, "description": "The current task, including delivery, usage and billing information.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/TaskNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitResponse" }, "500": { "$ref": "#/components/responses/InternalErrorResponse" }, "503": { "$ref": "#/components/responses/DependencyUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a video task", "tags": [ "Video" ] } }, "/v1/video/tasks/{task_id}/billing": { "get": { "description": "Retrieve the whole-task billing summary and one ordered page of permanent billing events. Use cursor and page_size to continue. The summary always covers the task, rather than only the current event page. An unknown task or one outside your team returns task_not_found.", "operationId": "getVideoTaskBilling", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/TaskID" }, { "$ref": "#/components/parameters/BillingCursor" }, { "$ref": "#/components/parameters/BillingPageSize" } ], "responses": { "200": { "content": { "application/json": { "example": { "billing_correlation_id": "billcorr_example_0001", "charged_amount": "0.361564", "collected_liability_amount": "0.361564", "currency": "USD", "events": [ { "adjustment_direction": null, "amount": "0.782453", "audit_reason": null, "billing_component": "generation_output", "billing_correlation_id": "billcorr_example_0001", "billing_event_id": "bevt_example_hold_0001", "charge_amount": "0.000000", "collected_liability_amount": "0.000000", "component_detail_code": null, "created_at": 0, "currency": "USD", "event_type": "hold_created", "funding_debit_amount": "0.000000", "funding_refund_amount": "0.000000", "receivable_amount": "0.000000", "receivable_direction": null, "refund_amount": "0.000000", "request_id": "req_example_0001", "settlement_status": "reserved", "task_id": "task_example_0001" }, { "adjustment_direction": null, "amount": "0.361564", "audit_reason": null, "billing_component": "generation_output", "billing_correlation_id": "billcorr_example_0001", "billing_event_id": "bevt_example_capture_0001", "charge_amount": "0.361564", "collected_liability_amount": "0.361564", "component_detail_code": null, "created_at": 2, "currency": "USD", "event_type": "charge_captured", "funding_debit_amount": "0.361564", "funding_refund_amount": "0.000000", "receivable_amount": "0.000000", "receivable_direction": null, "refund_amount": "0.000000", "request_id": "req_example_0001", "settlement_status": "settled", "task_id": "task_example_0001" }, { "adjustment_direction": null, "amount": "0.420889", "audit_reason": null, "billing_component": "generation_output", "billing_correlation_id": "billcorr_example_0001", "billing_event_id": "bevt_example_release_0001", "charge_amount": "0.000000", "collected_liability_amount": "0.000000", "component_detail_code": null, "created_at": 3, "currency": "USD", "event_type": "hold_released", "funding_debit_amount": "0.000000", "funding_refund_amount": "0.000000", "receivable_amount": "0.000000", "receivable_direction": null, "refund_amount": "0.000000", "request_id": "req_example_0001", "settlement_status": "settled", "task_id": "task_example_0001" } ], "final_actual_cost": "0.361564", "funding_debit_amount": "0.361564", "funding_refund_amount": "0.000000", "model": "dreamina-seedance-2-0-260128", "next_cursor": null, "object": "video.task.billing", "outstanding_receivable": "0.000000", "reconciliation": null, "refunded_liability_amount": "0.000000", "request_id": "req_example_0001", "reserved_amount": "0.782453", "settlement_status": "settled", "task_id": "task_example_0001", "task_status": "succeeded" }, "schema": { "$ref": "#/components/schemas/VideoTaskBilling" } } }, "description": "A whole-task billing summary with one ordered page of permanent events.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/TaskNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitResponse" }, "500": { "$ref": "#/components/responses/InternalErrorResponse" }, "503": { "$ref": "#/components/responses/DependencyUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read task billing", "tags": [ "Video" ] } }, "/v1/video/tasks/{task_id}/cancel": { "post": { "description": "Requires service.use permission and Idempotency-Key. Send an empty request body. Before generation starts, cancellation takes effect immediately: the task becomes cancelled and the full reserved amount is released. If billing is paused, the response still says effective and the release completes later. Once generation has started, cancellation returns not_effective; the task continues and billing proceeds normally. Retrying the same request with the same key replays the original response. Using that key for another task returns idempotency_conflict. A new key refers to the same cancellation operation and saves the task status at that response. A finished task with no cancellation operation returns task_not_cancellable. Unknown tasks and tasks outside your team return task_not_found, as with a task query. A rejected request does not reserve a new key.", "operationId": "cancelVideoTask", "parameters": [ { "$ref": "#/components/parameters/RequestID" }, { "$ref": "#/components/parameters/TaskID" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "content": { "application/json": { "examples": { "effective": { "value": { "cancel_operation_id": "cancelop_example_0001", "cancel_status": "effective", "reason_code": null, "task_id": "task_example_0001", "task_status_at_response": "cancelled" } }, "not_effective": { "value": { "cancel_operation_id": "cancelop_example_0001", "cancel_status": "not_effective", "reason_code": "generation_already_started", "task_id": "task_example_0001", "task_status_at_response": "succeeded" } }, "requested": { "value": { "cancel_operation_id": "cancelop_example_0001", "cancel_status": "requested", "reason_code": null, "task_id": "task_example_0001", "task_status_at_response": "processing" } } }, "schema": { "$ref": "#/components/schemas/CancelVideoTaskResponse" } } }, "description": "A permanent snapshot of the cancellation operation. effective means Cancelled; not_effective means Not cancelled. Continue checking the task and its billing.", "headers": { "Location": { "required": true, "schema": { "$ref": "#/components/schemas/TaskLocation" } }, "X-Request-ID": { "$ref": "#/components/headers/RequestID" } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/TaskNotFoundResponse" }, "409": { "$ref": "#/components/responses/CancellationConflictResponse" }, "429": { "$ref": "#/components/responses/RateLimitResponse" }, "500": { "$ref": "#/components/responses/InternalErrorResponse" }, "503": { "$ref": "#/components/responses/DependencyUnavailableResponse" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel a video task", "tags": [ "Video" ] } } }, "tags": [ { "name": "Assets" }, { "name": "Video" } ], "webhooks": { "task.billing_settled": { "post": { "description": "Chenvoya sends task.billing_settled after task.completed is delivered or abandoned and settlement reaches settled or settled_with_receivable. This event has its own seven-day delivery window. No billing notification is created if settlement is still pending thirty days after completion. The final charge matches the task query; it is zero for settled failed or cancelled tasks.", "operationId": "receiveTaskBillingSettled", "parameters": [ { "in": "header", "name": "Chenvoya-Event-Id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "Chenvoya-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackEventBody" } } }, "required": true }, "responses": { "204": { "description": "The notification was received. Any 2xx response confirms delivery; other responses and timeouts cause scheduled retries." } }, "summary": "Receive a billing settlement notification" } }, "task.completed": { "post": { "description": "Chenvoya sends task.completed when a task reaches succeeded, failed or cancelled. Successful tasks also wait for result delivery processing to finish. Delivery is at least once: retries keep the same event ID and original body bytes. Notifications have no download links. Read the task for current status and results. See Callbacks for signature verification, deduplication and retries.", "operationId": "receiveTaskCompleted", "parameters": [ { "in": "header", "name": "Chenvoya-Event-Id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "header", "name": "Chenvoya-Signature", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackEventBody" } } }, "required": true }, "responses": { "204": { "description": "The notification was received. Any 2xx response confirms delivery; other responses and timeouts cause scheduled retries." } }, "summary": "Receive a task completion notification" } } } }