{"components":{"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid_request, idempotency_key_required"},"Conflict":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"idempotency_conflict, conflict"},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"permission_denied, ip_not_allowed, account_disabled"},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"not_found (also for resources owned by others)"},"PaymentRequired":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"quota_exceeded, key_limit_exceeded"},"ServerError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"internal_error, no_available_channel, service_unavailable"},"TooManyRequests":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"rate_limited, concurrency_limited","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid_api_key"},"Unprocessable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid_parameter, asset_not_ready, authorization_required, budget_exceeded, storage_quota_exceeded"}},"schemas":{"ArkContent":{"properties":{"audio_url":{"properties":{"url":{"type":"string"}},"type":"object"},"image_url":{"properties":{"url":{"type":"string"}},"type":"object"},"role":{"type":"string"},"text":{"type":"string"},"type":{"enum":["text","image_url","video_url","audio_url"],"type":"string"},"video_url":{"properties":{"url":{"type":"string"}},"type":"object"}},"type":"object"},"ArkCreateRequest":{"properties":{"callback_url":{"type":"string"},"camera_fixed":{"type":"boolean"},"content":{"items":{"$ref":"#/components/schemas/ArkContent"},"type":"array"},"duration":{"type":"integer"},"execution_expires_after":{"type":"integer"},"generate_audio":{"type":"boolean"},"model":{"type":"string"},"ratio":{"type":"string"},"resolution":{"type":"string"},"return_last_frame":{"type":"boolean"},"seed":{"type":"integer"},"service_tier":{"enum":["default"],"type":"string"},"tools":{"items":{"properties":{"type":{"enum":["web_search"],"type":"string"}},"type":"object"},"type":"array"},"watermark":{"type":"boolean"}},"required":["model","content"],"type":"object"},"ArkTask":{"properties":{"content":{"properties":{"last_frame_url":{"type":"string"},"video_url":{"type":"string"}},"type":"object"},"created_at":{"type":"integer"},"duration":{"type":"integer"},"error":{"anyOf":[{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},{"type":"null"}]},"framespersecond":{"type":"integer"},"id":{"type":"string"},"model":{"type":"string"},"ratio":{"type":"string"},"resolution":{"type":"string"},"seed":{"type":"integer"},"status":{"enum":["queued","running","succeeded","failed","cancelled"],"type":"string"},"updated_at":{"type":"integer"},"usage":{"properties":{"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}},"type":"object"}},"type":"object"},"Asset":{"properties":{"created_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"download_url":{"type":"string"},"download_url_expires_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"group_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"height":{"anyOf":[{"type":"integer"},{"type":"null"}]},"id":{"examples":["ast_…"],"type":"string"},"media_type":{"enum":["image","video","audio"],"type":"string"},"mime":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"type":"string"},"object":{"const":"asset","type":"string"},"origin":{"type":"string"},"portrait_authorization_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"reference":{"description":"asset://\u003cid\u003e","type":"string"},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}]},"size_bytes":{"type":"integer"},"status":{"enum":["uploading","processing","active","needs_authorization","failed","deleting","deleted"],"type":"string"},"status_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"trust_kind":{"enum":["normal","virtual_portrait","real_portrait"],"type":"string"},"updated_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"version":{"type":"integer"},"width":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["id","status","media_type"],"type":"object"},"AssetGroup":{"properties":{"asset_count":{"type":"integer"},"created_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"Capabilities":{"properties":{"camera_fixed":{"type":"boolean"},"default_ratio":{"type":"string"},"default_resolution":{"type":"string"},"dimensions":{"additionalProperties":{"additionalProperties":{"items":{"type":"integer"},"maxItems":2,"minItems":2,"type":"array"},"type":"object"},"description":"Output size per resolution and ratio: {\"720p\": {\"16:9\": [1280, 720]}}.","type":"object"},"duration":{"properties":{"auto":{"description":"Whether -1 (model decides) is accepted.","type":"boolean"},"default":{"type":"integer"},"max":{"type":"integer"},"min":{"type":"integer"}},"type":"object"},"fps":{"type":"integer"},"generate_audio":{"properties":{"default":{"type":"boolean"},"supported":{"type":"boolean"}},"type":"object"},"inputs":{"properties":{"audio":{"$ref":"#/components/schemas/InputLimit"},"audio_requires_visual":{"type":"boolean"},"image":{"$ref":"#/components/schemas/InputLimit"},"max_total":{"type":"integer"},"video":{"$ref":"#/components/schemas/InputLimit"}},"type":"object"},"mode_ratios":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},"modes":{"items":{"enum":["text_to_video","first_frame","first_last_frame","reference"],"type":"string"},"type":"array"},"prompt_max_chars":{"type":"integer"},"ratios":{"items":{"type":"string"},"type":"array"},"resolutions":{"items":{"type":"string"},"type":"array"},"return_last_frame":{"type":"boolean"},"seed":{"type":"boolean"},"watermark":{"type":"boolean"},"web_search":{"type":"boolean"}},"type":"object"},"CreateAssetRequest":{"description":"Provide exactly one of upload_id and url (or send multipart/form-data with a file field).","properties":{"group_id":{"type":"string"},"media_type":{"enum":["image","video","audio"],"type":"string"},"name":{"type":"string"},"portrait_authorization_id":{"description":"Required for real_portrait.","type":"string"},"trust_kind":{"enum":["normal","virtual_portrait","real_portrait"],"type":"string"},"upload_id":{"description":"A completed upload.","type":"string"},"url":{"description":"An http(s) or data URL to import.","type":"string"}},"type":"object"},"CreateTaskRequest":{"properties":{"callback_url":{"description":"Public HTTPS address for the final-state webhook.","format":"uri","type":"string"},"camera_fixed":{"type":"boolean"},"duration":{"description":"Output seconds; -1 lets the model decide (the longest duration is reserved).","type":"integer"},"generate_audio":{"type":"boolean"},"inputs":{"items":{"$ref":"#/components/schemas/TaskInput"},"type":"array"},"max_budget":{"description":"Refuse with 422 budget_exceeded if the maximum possible cost is higher.","type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"model":{"examples":["seedance-2.0-standard"],"type":"string"},"prompt":{"type":"string"},"ratio":{"examples":["16:9"],"type":"string"},"resolution":{"examples":["720p"],"type":"string"},"return_last_frame":{"type":"boolean"},"seed":{"type":"integer"},"watermark":{"type":"boolean"},"web_search":{"type":"boolean"}},"required":["model"],"type":"object"},"Error":{"properties":{"error":{"properties":{"code":{"description":"Stable error code.","examples":["invalid_parameter"],"type":"string"},"details":{"additionalProperties":true,"type":"object"},"message":{"description":"Human-readable explanation.","type":"string"},"param":{"description":"The offending field, when there is one.","type":"string"},"request_id":{"description":"Trace ID; quote it to support.","type":"string"},"retryable":{"description":"Whether retrying the same request may succeed.","type":"boolean"}},"required":["code","message","retryable"],"type":"object"}},"required":["error"],"type":"object"},"InputLimit":{"properties":{"aspect_max":{"type":"number"},"aspect_min":{"type":"number"},"each_max_sec":{"type":"number"},"each_min_sec":{"type":"number"},"formats":{"items":{"type":"string"},"type":"array"},"max":{"type":"integer"},"max_bytes":{"type":"integer"},"max_side":{"type":"integer"},"min_side":{"type":"integer"},"total_max_sec":{"type":"number"}},"type":"object"},"Model":{"properties":{"capabilities":{"$ref":"#/components/schemas/Capabilities"},"description":{"type":"string"},"display_name":{"type":"string"},"family":{"type":"string"},"id":{"examples":["seedance-2.0-standard"],"type":"string"},"kind":{"type":"string"},"object":{"const":"model","type":"string"},"pricing":{"anyOf":[{"$ref":"#/components/schemas/Pricing"},{"type":"null"}]},"release_notes":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array"},"version":{"type":"string"}},"required":["id","capabilities"],"type":"object"},"OpenAICreateRequest":{"properties":{"callback_url":{"type":"string"},"content":{"items":{"properties":{"audio_url":{"properties":{"url":{"type":"string"}},"type":"object"},"image_url":{"properties":{"url":{"type":"string"}},"type":"object"},"role":{"type":"string"},"type":{"enum":["image_url","video_url","audio_url"],"type":"string"},"video_url":{"properties":{"url":{"type":"string"}},"type":"object"}},"type":"object"},"type":"array"},"extra_body":{"properties":{"provider_options":{"additionalProperties":true,"type":"object"}},"type":"object"},"generate_audio":{"type":"boolean"},"input_reference":{"anyOf":[{"format":"uri","type":"string"},{"properties":{"asset_id":{"type":"string"},"image_url":{"type":"string"}},"type":"object"}]},"metadata":{"type":"object"},"model":{"type":"string"},"prompt":{"type":"string"},"ratio":{"type":"string"},"resolution":{"type":"string"},"return_last_frame":{"type":"boolean"},"seconds":{"anyOf":[{"type":"string"},{"type":"integer"}]},"size":{"examples":["1280x720"],"type":"string"},"watermark":{"type":"boolean"}},"required":["model","prompt"],"type":"object"},"OpenAIVideo":{"properties":{"completed_at":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"type":"integer"},"error":{"anyOf":[{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}]},"id":{"type":"string"},"metadata":{"type":"object"},"model":{"type":"string"},"object":{"const":"video","type":"string"},"progress":{"type":"integer"},"seconds":{"type":"string"},"size":{"type":"string"},"status":{"enum":["queued","in_progress","completed","failed"],"type":"string"}},"type":"object"},"PortraitAuthorization":{"properties":{"created_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"grants":{"items":{"$ref":"#/components/schemas/PortraitGrant"},"type":"array"},"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"updated_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"}},"type":"object"},"PortraitGrant":{"properties":{"id":{"type":"string"},"label":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"updated_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"verification_expires_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"verification_url":{"type":"string"}},"type":"object"},"PriceRule":{"properties":{"key":{"type":"string"},"min_charge":{"type":"string"},"price":{"description":"Price per unit_size tokens.","type":"string"},"when":{"additionalProperties":{"type":"string"},"description":"Conditions, e.g. resolution and input_video.","type":"object"}},"type":"object"},"Pricing":{"properties":{"currency":{"type":"string"},"effective_from":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"examples_5s_16x9":{"additionalProperties":{"type":"string"},"type":"object"},"price_version":{"type":"string"},"rounding":{"type":"string"},"rules":{"items":{"$ref":"#/components/schemas/PriceRule"},"type":"array"},"unit":{"type":"string"},"unit_size":{"type":"integer"}},"type":"object"},"Quota":{"properties":{"available":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"balance":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"currency":{"type":"string"},"key":{"properties":{"daily_limit":{"anyOf":[{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},{"type":"null"}]},"daily_remaining":{"anyOf":[{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},{"type":"null"}]},"id":{"type":"string"},"name":{"type":"string"},"remaining":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"reserved":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"spent":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"timezone":{"type":"string"},"today_reserved":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"today_spent":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"total_limit":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"}},"type":"object"},"reserved":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"total_granted":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"total_settled":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"}},"type":"object"},"Task":{"properties":{"billing":{"properties":{"currency":{"type":"string"},"price_version":{"type":"string"},"released_amount":{"anyOf":[{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},{"type":"null"}]},"reserved_amount":{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},"settled_amount":{"anyOf":[{"description":"Decimal amount with 6 fractional digits, in the site currency.","examples":["5.009400"],"pattern":"^-?\\d+\\.\\d{6}$","type":"string"},{"type":"null"}]},"status":{"enum":["reserved","pending_usage","settled","released","waived"],"type":"string"}},"type":"object"},"client_request_id":{"type":"string"},"created_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"deadline_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"error":{"anyOf":[{"properties":{"action":{"description":"Suggested next step.","type":"string"},"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"type":"object"},{"type":"null"}]},"finished_at":{"anyOf":[{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},{"type":"null"}]},"id":{"examples":["task_01j…"],"type":"string"},"key_id":{"type":"string"},"metadata":{"additionalProperties":true,"type":"object"},"model":{"type":"string"},"model_version":{"type":"string"},"object":{"const":"video.generation","type":"string"},"protocol":{"enum":["platform","openai","ark","console"],"type":"string"},"request":{"properties":{"duration":{"type":"integer"},"generate_audio":{"type":"boolean"},"inputs":{"items":{"properties":{"asset_id":{"type":"string"},"role":{"type":"string"},"type":{"type":"string"}},"type":"object"},"type":"array"},"mode":{"type":"string"},"prompt":{"type":"string"},"ratio":{"type":"string"},"resolution":{"type":"string"},"return_last_frame":{"type":"boolean"},"seed":{"type":"integer"},"watermark":{"type":"boolean"},"web_search":{"type":"boolean"}},"type":"object"},"request_id":{"type":"string"},"result":{"anyOf":[{"properties":{"bytes":{"type":"integer"},"duration":{"type":"integer"},"expired":{"type":"boolean"},"fps":{"type":"integer"},"height":{"type":"integer"},"last_frame_url":{"type":"string"},"ratio":{"type":"string"},"resolution":{"type":"string"},"retention_expires_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"seed":{"type":"integer"},"url_expires_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"video_url":{"description":"Signed download URL; query the task again for a fresh one.","type":"string"},"width":{"type":"integer"}},"type":"object"},{"type":"null"}]},"status":{"$ref":"#/components/schemas/TaskStatus"},"updated_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"usage":{"anyOf":[{"properties":{"completion_tokens":{"type":"integer"},"items":{"items":{"properties":{"quantity":{"type":"integer"},"type":{"type":"string"},"unit":{"type":"string"}},"type":"object"},"type":"array"},"rule_key":{"type":"string"},"source":{"type":"string"}},"type":"object"},{"type":"null"}]}},"required":["id","object","status","model","created_at","billing"],"type":"object"},"TaskInput":{"properties":{"asset_id":{"description":"An asset in your library (ast_…).","type":"string"},"role":{"enum":["first_frame","last_frame","reference_image","reference_video","reference_audio"],"type":"string"},"type":{"enum":["image","video","audio"],"type":"string"},"url":{"description":"Alternatively an http(s) or data URL; it is imported into your library first.","type":"string"}},"required":["type"],"type":"object"},"TaskStatus":{"enum":["queued","preparing","running","recovering","reconciling","finalizing","succeeded","failed"],"type":"string"},"Upload":{"properties":{"expires_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"id":{"examples":["upl_…"],"type":"string"},"method":{"const":"PUT","type":"string"},"mode":{"enum":["single","multipart"],"type":"string"},"part_size":{"type":"integer"},"parts":{"items":{"properties":{"part_number":{"type":"integer"},"url":{"type":"string"}},"type":"object"},"type":"array"},"status":{"type":"string"},"url":{"description":"Signed PUT URL (mode=single).","type":"string"}},"type":"object"},"WebhookEvent":{"properties":{"created_at":{"description":"RFC 3339 timestamp (UTC).","format":"date-time","type":"string"},"data":{"$ref":"#/components/schemas/Task"},"id":{"examples":["evt_…"],"type":"string"},"type":{"enum":["video.generation.succeeded","video.generation.failed"],"type":"string"}},"required":["id","type","created_at","data"],"type":"object"}},"securitySchemes":{"bearerAuth":{"description":"Platform API key (sk-cn-… or sk-intl-…).","scheme":"bearer","type":"http"}}},"info":{"description":"All amounts are decimal strings with 6 fractional digits in the site currency. Errors use the Error schema with a stable code. Video tasks are asynchronous: create returns 202 with a task ID that never changes, even if the task moves to another route.","summary":"Seedance video generation with multi-route failover, a private asset library and usage-based billing.","title":"AILink API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v3/contents/generations/tasks":{"get":{"description":"Required key permission: `tasks_read`.","operationId":"arkListTasks","parameters":[{"description":"Page","in":"query","name":"page_num","required":false,"schema":{"type":"integer"}},{"description":"Size","in":"query","name":"page_size","required":false,"schema":{"type":"integer"}},{"description":"Status","in":"query","name":"filter.status","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ArkTask"},"type":"array"},"total":{"type":"integer"}},"type":"object"}}},"description":"Tasks"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"List tasks (Ark-compatible)","tags":["Ark-compatible"]},"post":{"description":"Required key permission: `generate`.","operationId":"arkCreateTask","parameters":[{"description":"Optional here; same semantics as on the platform endpoint.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArkCreateRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"id":{"type":"string"}},"type":"object"}}},"description":"Created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create a task (Ark-compatible)","tags":["Ark-compatible"]}},"/api/v3/contents/generations/tasks/{id}":{"delete":{"description":"Required key permission: `generate`.","operationId":"arkDeleteTask","parameters":[{"description":"Task ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Cancel a queued task (Ark-compatible)","tags":["Ark-compatible"]},"get":{"description":"Required key permission: `tasks_read`.","operationId":"arkGetTask","parameters":[{"description":"Task ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArkTask"}}},"description":"Task"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get a task (Ark-compatible)","tags":["Ark-compatible"]}},"/v1/account/quota":{"get":{"operationId":"getQuota","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quota"}}},"description":"Quota"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Account balance and this key's limits","tags":["Account"]}},"/v1/asset-groups":{"get":{"description":"Required key permission: `assets_read`.","operationId":"listAssetGroups","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AssetGroup"},"type":"array"},"object":{"type":"string"}},"type":"object"}}},"description":"Groups"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"List groups","tags":["Assets"]},"post":{"description":"Required key permission: `assets_write`.","operationId":"createAssetGroup","requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"type":"string"},"name":{"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetGroup"}}},"description":"Group"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Create a group","tags":["Assets"]}},"/v1/asset-groups/{id}":{"delete":{"description":"Required key permission: `assets_write`.","operationId":"deleteAssetGroup","parameters":[{"description":"Group ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Delete a group (its assets become ungrouped)","tags":["Assets"]},"patch":{"description":"Required key permission: `assets_write`.","operationId":"updateAssetGroup","parameters":[{"description":"Group ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"description":{"type":"string"},"name":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetGroup"}}},"description":"Group"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Edit a group","tags":["Assets"]}},"/v1/assets":{"get":{"description":"Required key permission: `assets_read`.","operationId":"listAssets","parameters":[{"description":"Page number, from 1.","in":"query","name":"page","required":false,"schema":{"minimum":1,"type":"integer"}},{"description":"Items per page (max 100).","in":"query","name":"page_size","required":false,"schema":{"maximum":100,"minimum":1,"type":"integer"}},{"description":"Start date (YYYY-MM-DD in the site timezone, or RFC 3339).","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"End date, inclusive (YYYY-MM-DD or RFC 3339).","in":"query","name":"to","required":false,"schema":{"type":"string"}},{"description":"Group","in":"query","name":"group_id","required":false,"schema":{"type":"string"}},{"description":"image, video or audio","in":"query","name":"media_type","required":false,"schema":{"type":"string"}},{"description":"Status","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"Kind","in":"query","name":"trust_kind","required":false,"schema":{"type":"string"}},{"description":"Name or ID","in":"query","name":"q","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Asset"},"type":"array"},"has_more":{"type":"boolean"},"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"}},"required":["data","total","page","page_size","has_more"],"type":"object"}}},"description":"Assets"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"List your assets","tags":["Assets"]},"post":{"description":"Required key permission: `assets_write`.","operationId":"createAsset","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetRequest"}},"multipart/form-data":{"schema":{"properties":{"file":{"format":"binary","type":"string"},"group_id":{"type":"string"},"media_type":{"type":"string"},"name":{"type":"string"},"portrait_authorization_id":{"type":"string"},"trust_kind":{"type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Created"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Import started (status processing)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"payload_too_large"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Create an asset from an upload, a URL or a file","tags":["Assets"]}},"/v1/assets/{id}":{"delete":{"description":"New tasks can no longer reference it. Running tasks that use it finish first; the file and its copies are removed afterwards.\n\nRequired key permission: `assets_write`.","operationId":"deleteAsset","parameters":[{"description":"Asset ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Deletion requested"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Request deletion of an asset and its copies","tags":["Assets"]},"get":{"description":"Required key permission: `assets_read`.","operationId":"getAsset","parameters":[{"description":"Asset ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Asset"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get an asset (with a 15-minute preview URL)","tags":["Assets"]},"patch":{"description":"Required key permission: `assets_write`.","operationId":"updateAsset","parameters":[{"description":"Asset ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"group_id":{"description":"Empty string removes it from its group.","type":"string"},"name":{"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}},"description":"Asset"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Rename an asset or move it to another group","tags":["Assets"]}},"/v1/models":{"get":{"operationId":"listModels","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Model"},"type":"array"},"object":{"const":"list","type":"string"}},"type":"object"}}},"description":"Models"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List models available to this key","tags":["Models"]}},"/v1/portrait-authorizations":{"get":{"description":"Required key permission: `assets_read`.","operationId":"listPortraitAuthorizations","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PortraitAuthorization"},"type":"array"},"object":{"type":"string"}},"type":"object"}}},"description":"Authorizations"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"List authorizations","tags":["Portraits"]},"post":{"description":"Required key permission: `assets_write`.","operationId":"createPortraitAuthorization","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortraitAuthorization"}}},"description":"Authorization with one grant per route"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Start a real-person authorization","tags":["Portraits"]}},"/v1/portrait-authorizations/{id}":{"get":{"description":"Required key permission: `assets_read`.","operationId":"getPortraitAuthorization","parameters":[{"description":"Authorization ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortraitAuthorization"}}},"description":"Authorization"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get an authorization","tags":["Portraits"]}},"/v1/portrait-authorizations/{id}/grants/{grant}/renew":{"post":{"description":"Required key permission: `assets_write`.","operationId":"renewPortraitGrant","parameters":[{"description":"Authorization ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Grant ID","in":"path","name":"grant","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortraitAuthorization"}}},"description":"Authorization"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"New verification link for one route","tags":["Portraits"]}},"/v1/uploads":{"post":{"description":"Files up to 32 MB get one signed PUT URL; larger files get one signed URL per part (part_size bytes). URLs are valid for 2 hours.\n\nRequired key permission: `assets_write`.","operationId":"createUpload","requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer"}},"required":["filename","size","content_type"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}},"description":"Upload session"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Start a signed upload to object storage","tags":["Assets"]}},"/v1/uploads/{id}/complete":{"post":{"description":"Required key permission: `assets_write`.","operationId":"completeUpload","parameters":[{"description":"Upload ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"parts":{"items":{"properties":{"etag":{"type":"string"},"part_number":{"type":"integer"}},"type":"object"},"type":"array"}},"type":"object"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"id":{"type":"string"},"size":{"type":"integer"},"status":{"type":"string"}},"type":"object"}}},"description":"Completed"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}},"summary":"Finish an upload","tags":["Assets"]}},"/v1/videos":{"get":{"description":"Required key permission: `tasks_read`.","operationId":"openaiListVideos","parameters":[{"description":"Max items (1-100, default 20)","in":"query","name":"limit","required":false,"schema":{"type":"integer"}},{"description":"Items to skip","in":"query","name":"offset","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OpenAIVideo"},"type":"array"},"first_id":{"type":"string"},"has_more":{"type":"boolean"},"last_id":{"type":"string"},"object":{"const":"list","type":"string"}},"type":"object"}}},"description":"Videos"},"401":{"$ref":"#/components/responses/Unauthorized"}},"summary":"List videos (OpenAI-compatible)","tags":["OpenAI-compatible"]},"post":{"description":"Required key permission: `generate`.","operationId":"openaiCreateVideo","parameters":[{"description":"Optional here; same semantics as on the platform endpoint.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAICreateRequest"}},"multipart/form-data":{"schema":{"properties":{"input_reference":{"format":"binary","type":"string"},"model":{"type":"string"},"prompt":{"type":"string"},"seconds":{"type":"string"},"size":{"type":"string"}},"required":["model","prompt"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIVideo"}}},"description":"Video"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create a video (OpenAI-compatible)","tags":["OpenAI-compatible"]}},"/v1/videos/generations":{"get":{"description":"Required key permission: `tasks_read`.","operationId":"listVideoTasks","parameters":[{"description":"Page number, from 1.","in":"query","name":"page","required":false,"schema":{"minimum":1,"type":"integer"}},{"description":"Items per page (max 100).","in":"query","name":"page_size","required":false,"schema":{"maximum":100,"minimum":1,"type":"integer"}},{"description":"Start date (YYYY-MM-DD in the site timezone, or RFC 3339).","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"End date, inclusive (YYYY-MM-DD or RFC 3339).","in":"query","name":"to","required":false,"schema":{"type":"string"}},{"description":"One or more statuses, comma-separated","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"Model ID","in":"query","name":"model","required":false,"schema":{"type":"string"}},{"description":"API key ID","in":"query","name":"key_id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Task"},"type":"array"},"has_more":{"type":"boolean"},"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"}},"required":["data","total","page","page_size","has_more"],"type":"object"}}},"description":"Tasks"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"List tasks","tags":["Video tasks"]},"post":{"description":"Validates the request against the model's capabilities, holds the maximum possible cost and returns at once. Failures after acceptance appear in the task's status and error, never as a different HTTP status.\n\nRequired key permission: `generate`.","operationId":"createVideoTask","parameters":[{"description":"Unique per business request. Replays with the same body return the original task (200); a different body returns 409 idempotency_conflict.","in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"duration":5,"inputs":[{"asset_id":"ast_\u003cID\u003e","role":"first_frame","type":"image"}],"model":"seedance-2.0-standard","prompt":"Slow push-in on the scene in the reference image","ratio":"16:9","resolution":"720p"},"schema":{"$ref":"#/components/schemas/CreateTaskRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}},"description":"Replay of an existing Idempotency-Key"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}},"description":"Accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"summary":"Create a video generation task","tags":["Video tasks"]}},"/v1/videos/generations/{id}":{"get":{"description":"Required key permission: `tasks_read`.","operationId":"getVideoTask","parameters":[{"description":"Task ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}},"description":"Task"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get a task: status, result, usage and cost","tags":["Video tasks"]}},"/v1/videos/generations/{id}/cancel":{"post":{"description":"Required key permission: `generate`.","operationId":"cancelVideoTask","parameters":[{"description":"Task ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}},"description":"Cancelled task"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Cancel a task not yet sent upstream","tags":["Video tasks"]}},"/v1/videos/{id}":{"get":{"description":"Required key permission: `tasks_read`.","operationId":"openaiGetVideo","parameters":[{"description":"Task ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIVideo"}}},"description":"Video"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Get a video (OpenAI-compatible)","tags":["OpenAI-compatible"]}},"/v1/videos/{id}/content":{"get":{"description":"Required key permission: `tasks_read`.","operationId":"openaiVideoContent","parameters":[{"description":"Task ID","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"video (default) or thumbnail","in":"query","name":"variant","required":false,"schema":{"type":"string"}}],"responses":{"307":{"description":"Redirect to a signed download URL"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}},"summary":"Download the video or its last frame","tags":["OpenAI-compatible"]}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://api.ail.run"}],"tags":[{"description":"Models, capabilities and prices available to the key.","name":"Models"},{"description":"Balance and key limits.","name":"Account"},{"description":"Private asset library: uploads, URL imports and groups.","name":"Assets"},{"description":"Real-person authorization for portrait assets.","name":"Portraits"},{"description":"Asynchronous video generation (platform contract).","name":"Video tasks"},{"description":"OpenAI Videos API shape, for the official OpenAI SDKs.","name":"OpenAI-compatible"},{"description":"Volcengine Ark task API shape, for the official Ark SDKs.","name":"Ark-compatible"}],"webhooks":{"videoGenerationFinished":{"post":{"description":"Sent to the task's callback_url. Verify X-AILink-Signature = \"t=\u003cunix\u003e,v1=\u003chex HMAC-SHA256(secret, \\\"\u003ct\u003e.\u003craw body\u003e\\\")\u003e\" with your webhook secret, reject timestamps older than 5 minutes and dedupe by event ID. Any 2xx response counts as delivered; failures are retried after 1 min, 5 min, 30 min, 2 h and 12 h.","operationId":"videoGenerationFinished","parameters":[{"in":"header","name":"X-AILink-Event-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-AILink-Event-Type","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-AILink-Timestamp","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-AILink-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Any 2xx acknowledges the event."}},"summary":"Final-state notification (video.generation.succeeded / video.generation.failed)"}}}}