{
  "components": {
    "callbacks": {},
    "examples": {},
    "headers": {},
    "links": {},
    "parameters": {},
    "pathItems": {},
    "requestBodies": {},
    "responses": {},
    "schemas": {},
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Image and video generation on AIsa models. The model field selects the model; GET /v1/models lists the enabled image and video models and the routes each one serves.",
    "title": "Media Generation",
    "version": "1",
    "x-aisa-capabilities": {
      "idempotency": "Idempotency-Key",
      "max_price": "X-AISA-Max-Price-USD",
      "quote": {
        "header": "X-AISA-Cost-Mode",
        "value": "quote"
      }
    },
    "x-aisa-catalogs": {
      "media-generation": {
        "description": "Image and video generation on AIsa models. The model field selects the model; GET /v1/models lists the enabled image and video models and the routes each one serves.",
        "title": "Media Generation",
        "x-aisa-capabilities": {
          "idempotency": "Idempotency-Key",
          "max_price": "X-AISA-Max-Price-USD",
          "quote": {
            "header": "X-AISA-Cost-Mode",
            "value": "quote"
          }
        },
        "x-aisa-document": {
          "facts_hash": "b05bd10c1f65804d1365e16e8d0787c01638f0abdea53ee0e7f966e42df0f0b5",
          "generator_version": "3",
          "protocol_version": "1",
          "schema_version": "1"
        },
        "x-aisa-plans": {
          "builder": 1.0,
          "display_plan": "payg",
          "payg": 1.0,
          "similarweb_payg": 1.0,
          "team": 1.0,
          "version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb"
        }
      }
    },
    "x-aisa-configured-paths": [
      "/v1/images/generations",
      "/v1/video/generations",
      "/v1/video/generations/{task_id}"
    ],
    "x-aisa-document": {
      "composer_version": "26",
      "document_hash": "sha256:db7f1b10e4feec69fd541e25bc0aa70851eb7596fab4af0d9d2b0dc9e0f10238",
      "facts_hash": "b05bd10c1f65804d1365e16e8d0787c01638f0abdea53ee0e7f966e42df0f0b5",
      "generator_version": "3",
      "protocol_version": "1",
      "response_pending": [],
      "schema_version": "1"
    },
    "x-aisa-plans": {
      "builder": 1.0,
      "display_plan": "payg",
      "payg": 1.0,
      "similarweb_payg": 1.0,
      "team": 1.0,
      "version": "e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb"
    },
    "x-aisa-provider": "media-generation"
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "openapi": "3.1.0",
  "paths": {
    "/v1/images/generations": {
      "post": {
        "description": "OpenAI-compatible image generation. The gateway requires model and resolves it from the model catalog; the remaining fields are forwarded to the selected model, which validates them. Accepted sizes are model-specific (Seedream requires at least 3,686,400 pixels, for example 2048x2048). Images are returned as url or b64_json, as the model produces them. With X-AISA-Cost-Mode: quote the route returns a cost_estimate instead and generates nothing.\n\n<!-- aisa-pricing:start -->\n当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。\n<!-- aisa-pricing:end -->",
        "operationId": "createImageGeneration",
        "parameters": [
          {
            "description": "Return a free, read-only cost quote for this caller and payload instead of generating.",
            "in": "header",
            "name": "X-AISA-Cost-Mode",
            "schema": {
              "enum": [
                "quote"
              ],
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "basic": {
                  "summary": "Single 2K image",
                  "value": {
                    "model": "seedream-5-0-260128",
                    "n": 1,
                    "prompt": "A cute red panda, ultra-detailed, cinematic lighting",
                    "size": "2048x2048"
                  }
                },
                "batch": {
                  "summary": "Four candidates for selection",
                  "value": {
                    "model": "seedream-5-0-260128",
                    "n": 4,
                    "prompt": "Oil painting of a rolling hillside at sunset",
                    "size": "2048x2048"
                  }
                },
                "minimum_size": {
                  "summary": "Exactly at minimum allowed size (1920×1920)",
                  "value": {
                    "model": "seedream-5-0-260128",
                    "n": 1,
                    "prompt": "A futuristic cyberpunk city, neon lights, rainy night, 8k",
                    "size": "1920x1920"
                  }
                }
              },
              "schema": {
                "properties": {
                  "image": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "items": {
                          "type": "string"
                        },
                        "type": "array"
                      }
                    ],
                    "description": "Reference image(s) for models that start from a picture, as an https or data: URL."
                  },
                  "model": {
                    "description": "An image model from GET /v1/models, for example seedream-5-0-260128, wan2.7-image or gpt-image-2.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "n": {
                    "default": 1,
                    "description": "Number of images, for models that support more than one.",
                    "minimum": 1,
                    "type": "integer"
                  },
                  "prompt": {
                    "description": "要生成的图像的文本描述。",
                    "minLength": 1,
                    "type": "string"
                  },
                  "size": {
                    "description": "WIDTHxHEIGHT, for example 2048x2048. Accepted sizes depend on the model.",
                    "example": "2048x2048",
                    "type": "string"
                  }
                },
                "required": [
                  "model",
                  "prompt"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "properties": {
                    "created": {
                      "type": "integer"
                    },
                    "data": {
                      "items": {
                        "additionalProperties": true,
                        "properties": {
                          "b64_json": {
                            "description": "Base64-encoded image bytes.",
                            "type": "string"
                          },
                          "revised_prompt": {
                            "type": "string"
                          },
                          "url": {
                            "description": "Temporary URL of the image.",
                            "type": "string"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Generated images."
          },
          "default": {
            "description": "Validation, authentication, balance or provider error. Provider refusals, such as content checks, keep their 4xx status."
          }
        },
        "summary": "Generate images",
        "x-aisa-capabilities": {
          "idempotency": "Idempotency-Key",
          "max_price": "X-AISA-Max-Price-USD",
          "quote": {
            "header": "X-AISA-Cost-Mode",
            "supported": true,
            "value": "quote"
          },
          "x402": false
        },
        "x-aisa-catalog-id": "media-generation",
        "x-aisa-contract-source": "handler",
        "x-aisa-docs-url": "https://aisa.one/docs/api-reference/chat/post_images-generations",
        "x-aisa-pricing": {
          "description": "Charged at the selected model's catalog price. A fixed-price model charges its listed price once per request, whatever n is; a token-priced model charges the usage it reports. A quote for the caller and payload says whether its amount is exact or an estimate.",
          "estimate_source": "unavailable",
          "estimate_unavailable_reason": "model_dependent_price",
          "kind": "model_catalog"
        },
        "x-aisa-revision": {
          "handler_contract_hash": "e9f28da56a2e0c6b37d2af892ab0ff032efb352b6846d48a006e2407d4a52903"
        },
        "x-aisa-runtime-operation": {
          "method": "POST",
          "operation_id": "createImageGeneration",
          "path": "/v1/images/generations"
        },
        "x-aisa-source": {
          "content_hash": "sha256:484be4e9322c28bcdf73b1f17c9ecde87e56057df21d9fba233e7994ad258e3c",
          "converter": "scripts/import_existing_contracts.py@1",
          "fetched_at": "2026-09-29T21:25:55+08:00",
          "kind": "manual",
          "owner": "AIsa-team/docs",
          "path_space": "public",
          "policy_revision": "sha256:0d852438cc6d89ccfe24b7d7803dc9eb1963516122a1afd4c32a751a30f5ab03",
          "refresh_policy": "manual",
          "review_period_days": 30,
          "url": "https://github.com/AIsa-team/docs/blob/7783840e4710bb00886143feab84606f8aaea67c/openapi/openai-images-generations.json"
        },
        "x-aisa-status": "enabled",
        "x-aisa-validation": "mixed"
      }
    },
    "/v1/video/generations": {
      "post": {
        "description": "Starts an asynchronous video generation task and returns it with status queued. The gateway requires model; the remaining fields are the selected model's own request fields and are forwarded to it. A video usually takes one to three minutes: poll retrieveVideoGeneration with the returned id until status is completed, failed or cancelled. Only a 503 whose code is video_submission_pending, with a non-empty id, means the task and its charge authorization were kept: retrieve it with that id and do not submit a replacement. Any other 503 means the service or the provider was unavailable and no task is pending; retry later. With X-AISA-Cost-Mode: quote the route returns a cost_estimate instead and creates no task.\n\n<!-- aisa-pricing:start -->\n当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。\n<!-- aisa-pricing:end -->",
        "operationId": "createVideoGeneration",
        "parameters": [
          {
            "description": "Return a free, read-only cost quote for this caller and payload instead of generating.",
            "in": "header",
            "name": "X-AISA-Cost-Mode",
            "schema": {
              "enum": [
                "quote"
              ],
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "content": [
                  {
                    "text": "A small red boat on a calm lake at dawn",
                    "type": "text"
                  }
                ],
                "duration": 5,
                "generate_audio": true,
                "model": "dreamina-seedance-2-0-260128",
                "ratio": "16:9",
                "watermark": false
              },
              "schema": {
                "additionalProperties": true,
                "properties": {
                  "content": {
                    "description": "Prompt and reference media, for Seedance models.",
                    "items": {
                      "additionalProperties": true,
                      "properties": {
                        "image_url": {
                          "properties": {
                            "url": {
                              "type": "string"
                            }
                          },
                          "type": "object"
                        },
                        "role": {
                          "description": "For images: first_frame, last_frame or reference_image; for videos: reference_video.",
                          "type": "string"
                        },
                        "text": {
                          "type": "string"
                        },
                        "type": {
                          "description": "text, image_url or video_url.",
                          "type": "string"
                        },
                        "video_url": {
                          "properties": {
                            "url": {
                              "type": "string"
                            }
                          },
                          "type": "object"
                        }
                      },
                      "required": [
                        "type"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "duration": {
                    "description": "Output length in seconds; part of the price.",
                    "minimum": 1,
                    "type": "integer"
                  },
                  "generate_audio": {
                    "type": "boolean"
                  },
                  "model": {
                    "description": "A video model from GET /v1/models, for example dreamina-seedance-2-0-260128 or wan2.7-t2v.",
                    "minLength": 1,
                    "type": "string"
                  },
                  "prompt": {
                    "description": "Text prompt, for models that take a plain prompt.",
                    "type": "string"
                  },
                  "ratio": {
                    "description": "Aspect ratio, for example 16:9, 9:16 or 1:1.",
                    "type": "string"
                  },
                  "resolution": {
                    "description": "For example 720p or 1080p; part of the price.",
                    "type": "string"
                  },
                  "watermark": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "model"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "completed_at": {
                      "description": "Unix seconds; present once the task has ended.",
                      "type": "integer"
                    },
                    "created_at": {
                      "description": "Unix seconds.",
                      "type": "integer"
                    },
                    "error": {
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "id": {
                      "type": "string"
                    },
                    "model": {
                      "type": "string"
                    },
                    "object": {
                      "const": "video.generation",
                      "type": "string"
                    },
                    "progress": {
                      "description": "For example 0% or 100%.",
                      "type": "string"
                    },
                    "result": {
                      "description": "The model's output once completed, including the video URL (video_url or url)."
                    },
                    "status": {
                      "enum": [
                        "queued",
                        "in_progress",
                        "completed",
                        "failed",
                        "cancelled",
                        "unknown"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "status",
                    "model",
                    "created_at",
                    "progress"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The task was created."
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "additionalProperties": false,
                      "properties": {
                        "code": {
                          "const": "video_submission_pending",
                          "type": "string"
                        },
                        "error": {
                          "type": "string"
                        },
                        "id": {
                          "description": "The kept task; pass it to retrieveVideoGeneration.",
                          "minLength": 1,
                          "type": "string"
                        }
                      },
                      "required": [
                        "error",
                        "code",
                        "id"
                      ],
                      "type": "object"
                    },
                    {
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Either the service or the provider was unavailable and no task is pending (retry later), or the submission needs reconciliation. Only the second has code video_submission_pending and a non-empty id: that task and its charge authorization are kept; retrieve it with the id and do not submit a replacement."
          },
          "default": {
            "description": "Validation, authentication, balance or provider error. Provider refusals, such as content checks, keep their 4xx status."
          }
        },
        "summary": "Create a video generation task",
        "x-aisa-capabilities": {
          "idempotency": "Idempotency-Key",
          "max_price": "X-AISA-Max-Price-USD",
          "mpp": false,
          "quote": {
            "header": "X-AISA-Cost-Mode",
            "supported": true,
            "value": "quote"
          },
          "x402": false
        },
        "x-aisa-catalog-id": "media-generation",
        "x-aisa-contract-source": "handler",
        "x-aisa-docs-url": "https://aisa.one/docs/api-reference/media-generation/createVideoGeneration",
        "x-aisa-lifecycle": {
          "action": "submit",
          "kind": "asynchronous"
        },
        "x-aisa-pricing": {
          "description": "Charged at the selected model's catalog price, which can depend on the requested resolution and duration and is listed per second, per request or by tokens. The charge is held at submission and settled when the task ends. A quote for the caller and payload says whether its amount is exact or an estimate.",
          "estimate_source": "unavailable",
          "estimate_unavailable_reason": "model_dependent_price",
          "kind": "model_catalog"
        },
        "x-aisa-revision": {
          "handler_contract_hash": "3f814885c369011a20079676ad88db6c8744cf3be09f3e7b061664aa2b41e94a"
        },
        "x-aisa-runtime-operation": {
          "method": "POST",
          "operation_id": "createVideoGeneration",
          "path": "/v1/video/generations"
        },
        "x-aisa-source": {
          "content_hash": "sha256:989befbd5e6a4c0106a71aa7064db1749cef3232f0396b1ab715623d87943f0e",
          "converter": "manual:aisaservices-video-handler-contract@1",
          "fetched_at": "2026-10-30T20:00:00+08:00",
          "kind": "manual",
          "owner": "AIsa-team/docs",
          "path_space": "public",
          "policy_revision": "sha256:39ef87da0423db20b45d0ea4cc09a0b2c1aac7c3710f536685de2165cef00bf0",
          "refresh_policy": "manual",
          "review_period_days": 30,
          "url": "https://github.com/AIsa-team/AIsaServices/blob/c03a076b24caee6fed1665fede5f72fa1f7b6700/services/api-service/internal/httpapi/api_contract_media.go"
        },
        "x-aisa-status": "enabled",
        "x-aisa-validation": "mixed",
        "x-codeSamples": [
          {
            "label": "Reference example",
            "lang": "text",
            "source": "# Fixed reference example. Playground inputs do not update this sample.\ncurl --request POST \\\n  --url https://api.aisa.one/v1/video/generations \\\n  --header 'Authorization: Bearer <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"model\": \"dreamina-seedance-2-0-260128\",\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"text\": \"A small red boat on a calm lake at dawn\"\n    }\n  ],\n  \"ratio\": \"16:9\",\n  \"duration\": 5,\n  \"generate_audio\": true,\n  \"watermark\": false\n}'"
          }
        ]
      }
    },
    "/v1/video/generations/{task_id}": {
      "get": {
        "description": "Returns a video generation task created with the same account. When status is completed, result holds the model's output, including the video URL; when status is failed, error.message says why.\n\n<!-- aisa-pricing:start -->\n当前未提供请求参考价格；请使用接口支持的报价功能确认费用。 最终费用以账户适用价格及实际结算为准。\n<!-- aisa-pricing:end -->",
        "operationId": "retrieveVideoGeneration",
        "parameters": [
          {
            "description": "The id returned when the task was created.",
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "completed_at": {
                      "description": "Unix seconds; present once the task has ended.",
                      "type": "integer"
                    },
                    "created_at": {
                      "description": "Unix seconds.",
                      "type": "integer"
                    },
                    "error": {
                      "properties": {
                        "message": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "id": {
                      "type": "string"
                    },
                    "model": {
                      "type": "string"
                    },
                    "object": {
                      "const": "video.generation",
                      "type": "string"
                    },
                    "progress": {
                      "description": "For example 0% or 100%.",
                      "type": "string"
                    },
                    "result": {
                      "description": "The model's output once completed, including the video URL (video_url or url)."
                    },
                    "status": {
                      "enum": [
                        "queued",
                        "in_progress",
                        "completed",
                        "failed",
                        "cancelled",
                        "unknown"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "object",
                    "status",
                    "model",
                    "created_at",
                    "progress"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The task."
          },
          "404": {
            "description": "No task with this id belongs to the account."
          },
          "default": {
            "description": "Validation, authentication, balance or provider error. Provider refusals, such as content checks, keep their 4xx status."
          }
        },
        "summary": "Retrieve a video generation task",
        "x-aisa-capabilities": {
          "idempotency": "Idempotency-Key",
          "max_price": "X-AISA-Max-Price-USD",
          "mpp": false,
          "quote": {
            "reason": "cost_quote_unsupported",
            "supported": false
          },
          "x402": false
        },
        "x-aisa-catalog-id": "media-generation",
        "x-aisa-contract-source": "handler",
        "x-aisa-docs-url": "https://aisa.one/docs/api-reference/media-generation/retrieveVideoGeneration",
        "x-aisa-lifecycle": {
          "action": "retrieve",
          "kind": "asynchronous"
        },
        "x-aisa-pricing": {
          "description": "Reading a task is free; the task's charge settles when it ends.",
          "kind": "no_customer_charge"
        },
        "x-aisa-revision": {
          "handler_contract_hash": "713455922bd554c36abe5350aa3cc8c90df92ad91e50bf76df0f73248bb79b4e"
        },
        "x-aisa-runtime-operation": {
          "method": "GET",
          "operation_id": "retrieveVideoGeneration",
          "path": "/v1/video/generations/{task_id}"
        },
        "x-aisa-status": "enabled",
        "x-aisa-validation": "runtime"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ]
}