{
  "openapi": "3.1.0",
  "info": {
    "title": "Seedance 2.5 API on EvoLink",
    "version": "1.0.0",
    "description": "An independent integration aid for the live Seedance 2.5 route on EvoLink. EvoLink provider documentation remains authoritative for accepted fields, current pricing, account limits, and error behavior."
  },
  "x-contract-status": "live-integration-aid",
  "x-upstream-official-api-live": true,
  "x-route-live": true,
  "x-live-route-available": true,
  "x-verification-note": "The official API and EvoLink integration are live for the 2026-08-07 publication. Confirm current price and account-specific limits in EvoLink before scaled production traffic.",
  "servers": [
    {
      "url": "https://api.evolink.ai",
      "description": "EvoLink production API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "externalDocs": {
    "description": "Seedance 2.5 integration guide and current route status",
    "url": "https://seedance25api.io/api"
  },
  "paths": {
    "/v1/videos/generations": {
      "post": {
        "operationId": "createSeedance25Generation",
        "summary": "Create an asynchronous Seedance 2.5 video generation task",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VideoGenerationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncTask"
                }
              }
            }
          },
          "400": {
            "description": "Request validation error"
          },
          "401": {
            "description": "Authentication error"
          },
          "429": {
            "description": "Rate-limit error"
          },
          "5XX": {
            "description": "Provider or upstream service error"
          }
        }
      }
    },
    "/v1/tasks/{task_id}": {
      "get": {
        "operationId": "getSeedance25Task",
        "summary": "Get asynchronous task status and result URLs",
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current task state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsyncTask"
                }
              }
            }
          },
          "404": {
            "description": "Task not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Create an EvoLink API key and pass it as Authorization: Bearer $EVOLINK_API_KEY."
      }
    },
    "schemas": {
      "VideoGenerationRequest": {
        "description": "Workflow-specific request. The model ID selects the accepted shape: text-to-video takes no reference media, image-to-video takes 1–2 frame images, reference-to-video requires at least one reference input. EvoLink provider documentation remains authoritative for any additional optional fields.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextToVideoRequest"
          },
          {
            "$ref": "#/components/schemas/ImageToVideoRequest"
          },
          {
            "$ref": "#/components/schemas/ReferenceToVideoRequest"
          }
        ],
        "discriminator": {
          "propertyName": "model",
          "mapping": {
            "seedance-2.5-text-to-video": "#/components/schemas/TextToVideoRequest",
            "seedance-2.5-image-to-video": "#/components/schemas/ImageToVideoRequest",
            "seedance-2.5-reference-to-video": "#/components/schemas/ReferenceToVideoRequest"
          }
        }
      },
      "TextToVideoRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "additionalProperties": false,
        "properties": {
          "model": {
            "type": "string",
            "const": "seedance-2.5-text-to-video"
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "description": "Creative instruction; text-to-video accepts no reference media."
          },
          "duration": {
            "$ref": "#/components/schemas/Duration"
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/AspectRatio"
          },
          "generate_audio": {
            "$ref": "#/components/schemas/GenerateAudio"
          },
          "content_filter": {
            "$ref": "#/components/schemas/ContentFilter"
          },
          "model_params": {
            "type": "object",
            "additionalProperties": true,
            "description": "Documented extension object for text-to-video (e.g. web_search).",
            "properties": {
              "web_search": {
                "type": "boolean",
                "default": false
              }
            }
          },
          "callback_url": {
            "$ref": "#/components/schemas/CallbackUrl"
          }
        }
      },
      "ImageToVideoRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt",
          "image_urls"
        ],
        "additionalProperties": false,
        "properties": {
          "model": {
            "type": "string",
            "const": "seedance-2.5-image-to-video"
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "description": "Required creative instruction guiding motion between the provided frames."
          },
          "image_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1,
            "maxItems": 2,
            "description": "First frame, or first and last frame — 1 to 2 images."
          },
          "duration": {
            "$ref": "#/components/schemas/Duration"
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/AspectRatio"
          },
          "generate_audio": {
            "$ref": "#/components/schemas/GenerateAudio"
          },
          "content_filter": {
            "$ref": "#/components/schemas/ContentFilter"
          },
          "callback_url": {
            "$ref": "#/components/schemas/CallbackUrl"
          }
        }
      },
      "ReferenceToVideoRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "image_urls"
            ]
          },
          {
            "required": [
              "video_urls"
            ]
          },
          {
            "required": [
              "audio_urls"
            ]
          }
        ],
        "properties": {
          "model": {
            "type": "string",
            "const": "seedance-2.5-reference-to-video"
          },
          "prompt": {
            "type": "string",
            "minLength": 1,
            "description": "Creative instruction; at least one reference input is required."
          },
          "image_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1,
            "maxItems": 30,
            "description": "Up to 30 reference images."
          },
          "video_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1,
            "maxItems": 10,
            "description": "Up to 10 reference videos."
          },
          "audio_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "minItems": 1,
            "maxItems": 10,
            "description": "Up to 10 reference audio files."
          },
          "duration": {
            "$ref": "#/components/schemas/Duration"
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "aspect_ratio": {
            "$ref": "#/components/schemas/AspectRatio"
          },
          "generate_audio": {
            "$ref": "#/components/schemas/GenerateAudio"
          },
          "content_filter": {
            "$ref": "#/components/schemas/ContentFilter"
          },
          "callback_url": {
            "$ref": "#/components/schemas/CallbackUrl"
          }
        }
      },
      "Duration": {
        "type": "integer",
        "minimum": 4,
        "maximum": 30,
        "default": 5,
        "description": "Supported launch range: 4–30 seconds."
      },
      "Quality": {
        "type": "string",
        "enum": [
          "480p",
          "720p"
        ],
        "default": "720p",
        "description": "Supported launch tiers. 4K is not an EvoLink launch API tier."
      },
      "AspectRatio": {
        "type": "string",
        "enum": [
          "16:9",
          "9:16",
          "1:1",
          "4:3",
          "3:4",
          "21:9",
          "adaptive"
        ],
        "default": "adaptive",
        "description": "Documented output aspect ratios; adaptive follows the input or prompt."
      },
      "GenerateAudio": {
        "type": "boolean",
        "default": true,
        "description": "Generate synchronized audio when supported by the selected workflow."
      },
      "ContentFilter": {
        "type": "boolean",
        "default": true,
        "description": "Documented content-filter toggle; disabling it carries a documented billing surcharge — confirm current billing in the EvoLink console."
      },
      "CallbackUrl": {
        "type": "string",
        "format": "uri",
        "description": "Optional callback destination for asynchronous task updates."
      },
      "AsyncTask": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Asynchronous task ID."
          },
          "model": {
            "type": "string",
            "description": "Actual model reported by the provider."
          },
          "object": {
            "type": "string",
            "examples": [
              "video.generation.task"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "completed",
              "failed"
            ],
            "description": "EvoLink asynchronous task lifecycle."
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "results": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            },
            "description": "Generated result URLs when the task is complete."
          },
          "task_info": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "can_cancel": {
                "type": "boolean"
              },
              "estimated_time": {
                "type": "number"
              }
            }
          },
          "usage": {
            "type": "object",
            "additionalProperties": true,
            "description": "Provider usage data when returned; use the EvoLink console as the billing source of truth."
          },
          "error": {
            "description": "Provider error payload when a task fails."
          }
        }
      }
    }
  }
}