AiVideoEditor
免费开始
菜单

API 参考

API 版本 2026-11-09 · 下载 OpenAPI 3.1 YAML

身份验证使用工作区范围的产品密钥:Authorization: Bearer pk_v1_…。密钥带有明确的作用域和可选的账号白名单;它们绝不能创建其他密钥或更改账单。 所有变更操作都需要 Idempotency-Key 请求头;编辑和排期还需要 expectedVersion。发布和排期返回 202 Accepted,每个目标一个交付 ID:202 绝不表示任何内容已发布。通过 GET /posts/{id}、客户 webhook 或带退避的有界轮询验证结果。 错误使用契约 v1 的规范化信封:code、安全的 message、fieldErrors、destinationErrors、retryable、retryAfterSeconds 和 requestId。刻意没有发布额度或配额错误代码。

身份验证

以 "Authorization: Bearer pk_v1_…" 的形式发送工作区产品密钥。每个操作都列出了所需的作用域。参见身份验证与权限。

GET /capabilities

许可目标的合格格式与选项

需要作用域 accounts:read。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "accounts"
  ],
  "summary": "许可目标的合格格式与选项",
  "description": "需要作用域 `accounts:read`。",
  "responses": {
    "200": {
      "description": "Capability list",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "capabilities",
              "requestId"
            ],
            "properties": {
              "capabilities": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Capability"
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /accounts

列出此密钥可见的目标账号

遵守密钥的账号白名单。需要作用域 accounts:read。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "accounts"
  ],
  "summary": "列出此密钥可见的目标账号",
  "description": "遵守密钥的账号白名单。需要作用域 `accounts:read`。",
  "parameters": [
    {
      "$ref": "#/components/parameters/cursor"
    },
    {
      "$ref": "#/components/parameters/limit"
    }
  ],
  "responses": {
    "200": {
      "description": "Account page",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "accounts",
              "requestId"
            ],
            "properties": {
              "accounts": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Account"
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /accounts/{id}/tiktok/settings

读取许可的已连接账号的已验证 TikTok 创作者设置

需要 accounts:read 和密钥的账号白名单。此读取绝不提供人类发布同意。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "accounts"
  ],
  "summary": "读取许可的已连接账号的已验证 TikTok 创作者设置",
  "description": "需要 accounts:read 和密钥的账号白名单。此读取绝不提供人类发布同意。",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Current typed creator settings; a person must confirm choices in the composer",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "settings",
              "humanConfirmationRequired",
              "requestId"
            ],
            "properties": {
              "settings": {
                "$ref": "#/components/schemas/TikTokCreatorSettings"
              },
              "humanConfirmationRequired": {
                "type": "boolean",
                "const": true
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/upload-intents

预留字节并返回直接上传指令

需要作用域 media:write 加上一个 Idempotency-Key。字节使用返回的指令直接上传到私有对象存储;它们绝不经过此 API。不存在永久的公共媒体 URL。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "media"
  ],
  "summary": "预留字节并返回直接上传指令",
  "description": "需要作用域 `media:write` 加上一个 Idempotency-Key。字节使用返回的指令直接上传到私有对象存储;它们绝不经过此 API。不存在永久的公共媒体 URL。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UploadIntentRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Upload instructions created",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UploadIntentResponse"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /media/{id}

媒体状态与过期(无永久公共 URL)

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "media"
  ],
  "summary": "媒体状态与过期(无永久公共 URL)",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    }
  ],
  "responses": {
    "200": {
      "description": "Media status",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "media",
              "requestId"
            ],
            "properties": {
              "media": {
                "$ref": "#/components/schemas/MediaStatus"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/{id}/upload-parts

刷新现有上传会话中的 1 到 64 个 multipart PUT URL

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "media"
  ],
  "summary": "刷新现有上传会话中的 1 到 64 个 multipart PUT URL",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "fromPart",
            "toPart"
          ],
          "properties": {
            "fromPart": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000
            },
            "toPart": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Fresh upload URLs; toPart must be at least fromPart and at most fromPart + 63",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "sessionId",
              "parts",
              "requestId"
            ],
            "properties": {
              "sessionId": {
                "type": "string",
                "format": "uuid"
              },
              "requestId": {
                "type": "string"
              },
              "parts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "partNumber",
                    "url",
                    "expiresAt"
                  ],
                  "properties": {
                    "partNumber": {
                      "type": "integer"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/{id}/abandon

放弃未完成的上传并释放其存储预留

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "media"
  ],
  "summary": "放弃未完成的上传并释放其存储预留",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Abandoned; failed external cleanup remains durably queued",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "abandoned",
              "requestId"
            ],
            "properties": {
              "abandoned": {
                "type": "boolean",
                "const": true
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /media/{id}/finalize

验证已上传的对象并使其可用

需要作用域 media:write 加上一个 Idempotency-Key。服务器针对不可变的最终副本验证大小/MIME 和有界签名;字节预留只结算一次。只发送会话标识(适用时加上 multipart 分片回执):服务器自行观察所有元数据。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "media"
  ],
  "summary": "验证已上传的对象并使其可用",
  "description": "需要作用域 `media:write` 加上一个 Idempotency-Key。服务器针对不可变的最终副本验证大小/MIME 和有界签名;字节预留只结算一次。只发送会话标识(适用时加上 multipart 分片回执):服务器自行观察所有元数据。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FinalizeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Finalized",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "media",
              "requestId"
            ],
            "properties": {
              "media": {
                "$ref": "#/components/schemas/FinalizeResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts

创建草稿

需要作用域 posts:write 加上一个 Idempotency-Key。请求体按契约 v1 的严格 DraftInputSchema 解析;重复的目标账号会被拒绝。保存是宽松的:发布前先校验。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "创建草稿",
  "description": "需要作用域 `posts:write` 加上一个 Idempotency-Key。请求体按契约 v1 的严格 DraftInputSchema 解析;重复的目标账号会被拒绝。保存是宽松的:发布前先校验。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DraftInput"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Draft created",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "post",
              "requestId"
            ],
            "properties": {
              "post": {
                "$ref": "#/components/schemas/DraftSaveResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /posts

列出帖子

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "列出帖子",
  "parameters": [
    {
      "$ref": "#/components/parameters/cursor"
    },
    {
      "$ref": "#/components/parameters/limit"
    },
    {
      "name": "state",
      "in": "query",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Post page",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "posts",
              "requestId"
            ],
            "properties": {
              "posts": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PostListItem"
                }
              },
              "nextCursor": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /posts/{id}

帖子聚合与按目标状态

“提供方已接受”不等于“已发布”。原生链接只在确认回执之后出现;缺少永久链接不是失败的证明。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "帖子聚合与按目标状态",
  "description": "“提供方已接受”不等于“已发布”。原生链接只在确认回执之后出现;缺少永久链接不是失败的证明。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    }
  ],
  "responses": {
    "200": {
      "description": "Post status",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "post",
              "requestId"
            ],
            "properties": {
              "post": {
                "$ref": "#/components/schemas/PostStatus"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

PATCH /posts/{id}

编辑草稿(带版本检查)

需要 Idempotency-Key 和 expectedVersion。过期的版本会返回 409 revision_conflict,并在 error.details.currentVersion 中包含当前版本。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "编辑草稿(带版本检查)",
  "description": "需要 Idempotency-Key 和 expectedVersion。过期的版本会返回 409 revision_conflict,并在 `error.details.currentVersion` 中包含当前版本。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/DraftUpdateInput"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated draft",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "post",
              "requestId"
            ],
            "properties": {
              "post": {
                "$ref": "#/components/schemas/DraftSaveResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts/{id}/validate

结构化的按目标校验(非变更操作)

当目标存在问题(内容问题绝不会作为错误状态返回)时,返回 200 和 validation.valid=false。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "结构化的按目标校验(非变更操作)",
  "description": "当目标存在问题(内容问题绝不会作为错误状态返回)时,返回 200 和 `validation.valid=false`。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "expectedVersion": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Validation result",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "validation",
              "requestId"
            ],
            "properties": {
              "validation": {
                "$ref": "#/components/schemas/ValidationResult"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts/{id}/publish

立即发布(202)

需要作用域 posts:publish 加上一个 Idempotency-Key。可选的 expectedVersion 应用与编辑相同的乐观并发保证。每个目标返回一个交付 ID;绝不声称已发布。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "立即发布(202)",
  "description": "需要作用域 `posts:publish` 加上一个 Idempotency-Key。可选的 `expectedVersion` 应用与编辑相同的乐观并发保证。每个目标返回一个交付 ID;绝不声称已发布。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "expectedVersion": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Accepted for dispatch",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AcceptedOperation"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /posts/{id}/schedule

排期冻结的修订版(202)

需要作用域 posts:publish 加上 Idempotency-Key 和 expectedVersion。整个批次使用一个时刻;必须是未来时间且在 90 天期限内(由共享服务强制执行)。V1 中 revisionId 必须为 null:不支持选择任意修订版,会被拒绝。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "posts"
  ],
  "summary": "排期冻结的修订版(202)",
  "description": "需要作用域 `posts:publish` 加上 Idempotency-Key 和 expectedVersion。整个批次使用一个时刻;必须是未来时间且在 90 天期限内(由共享服务强制执行)。V1 中 `revisionId` 必须为 null:不支持选择任意修订版,会被拒绝。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ScheduleRequest"
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Scheduled",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AcceptedOperation"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /deliveries/{id}/cancel

在安全未领取时取消一个目标任务

需要作用域 posts:publish 加上 Idempotency-Key。已提交的交付会返回 409 too_late_to_cancel,并带有真实状态。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "deliveries"
  ],
  "summary": "在安全未领取时取消一个目标任务",
  "description": "需要作用域 `posts:publish` 加上 Idempotency-Key。已提交的交付会返回 409 too_late_to_cancel,并带有真实状态。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "responses": {
    "200": {
      "description": "Cancellation result",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "delivery",
              "requestId"
            ],
            "properties": {
              "delivery": {
                "type": "object",
                "required": [
                  "deliveryId",
                  "canceled",
                  "state"
                ],
                "properties": {
                  "deliveryId": {
                    "type": "string"
                  },
                  "canceled": {
                    "type": "boolean"
                  },
                  "state": {
                    "type": "string"
                  }
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /deliveries/{id}/retry

重试一个已知失败的目标

需要作用域 posts:publish 加上 Idempotency-Key。未知结果或已成功的交付会被拒绝:重试可能重复发布该帖子。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "deliveries"
  ],
  "summary": "重试一个已知失败的目标",
  "description": "需要作用域 `posts:publish` 加上 Idempotency-Key。未知结果或已成功的交付会被拒绝:重试可能重复发布该帖子。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "responses": {
    "200": {
      "description": "Retry accepted",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "delivery",
              "requestId"
            ],
            "properties": {
              "delivery": {
                "type": "object",
                "required": [
                  "deliveryId",
                  "state"
                ],
                "properties": {
                  "deliveryId": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  }
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /usage

套餐、账号/席位/存储用量、活动与速率信息

需要作用域 usage:read。不包含任何形式的剩余发布计数器:每个付费套餐的发布量都不限。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "usage"
  ],
  "summary": "套餐、账号/席位/存储用量、活动与速率信息",
  "description": "需要作用域 `usage:read`。不包含任何形式的剩余发布计数器:每个付费套餐的发布量都不限。\n",
  "responses": {
    "200": {
      "description": "Usage snapshot",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "usage",
              "requestId"
            ],
            "properties": {
              "usage": {
                "$ref": "#/components/schemas/Usage"
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

POST /webhooks

注册客户事件目标

需要作用域 webhooks:manage 加上 Idempotency-Key。仅限 HTTPS;SSRF 验证(协议、凭据、有界 DNS 解析地址)在存储之前运行。签名密钥只在第一次创建响应中返回:幂等重放会返回不含密钥的端点。创建还会入队一个定向的验证事件。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "webhooks"
  ],
  "summary": "注册客户事件目标",
  "description": "需要作用域 `webhooks:manage` 加上 Idempotency-Key。仅限 HTTPS;SSRF 验证(协议、凭据、有界 DNS 解析地址)在存储之前运行。签名密钥只在第一次创建响应中返回:幂等重放会返回不含密钥的端点。创建还会入队一个定向的验证事件。\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateWebhookRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Endpoint created (secret shown once)",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "webhook",
              "requestId"
            ],
            "properties": {
              "webhook": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEndpoint"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "secret": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Present only on the first successful creation; null on replay."
                      }
                    }
                  }
                ]
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "422": {
      "$ref": "#/components/responses/Validation"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

GET /webhooks

列出事件目标(不含机密)

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "webhooks"
  ],
  "summary": "列出事件目标(不含机密)",
  "responses": {
    "200": {
      "description": "Endpoint list",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "webhooks",
              "requestId"
            ],
            "properties": {
              "webhooks": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              },
              "requestId": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

DELETE /webhooks/{id}

移除一个事件目标

需要作用域 webhooks:manage 和 Idempotency-Key(重复是安全的)。

操作详情包括参数、请求体、响应和组件引用。被引用的定义显示在下方。

{
  "tags": [
    "webhooks"
  ],
  "summary": "移除一个事件目标",
  "description": "需要作用域 `webhooks:manage` 和 Idempotency-Key(重复是安全的)。",
  "parameters": [
    {
      "$ref": "#/components/parameters/id"
    },
    {
      "$ref": "#/components/parameters/idempotencyKey"
    }
  ],
  "responses": {
    "204": {
      "description": "Deleted",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/requestId"
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/Forbidden"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    }
  }
}

共享定义

securitySchemes

productKey
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "pk_v1_… (product key; NOT a Supabase key)"
}

parameters

id
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
cursor
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
limit
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100,
    "default": 25
  }
}
idempotencyKey
{
  "name": "Idempotency-Key",
  "in": "header",
  "required": true,
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 255
  },
  "description": "相同密钥 + 相同的规范化请求体会重放已记录的结果;相同密钥 + 不同请求体会返回 409 idempotency_conflict。\n"
}

headers

requestId
{
  "description": "每个请求的关联 ID,也会在错误信封中回显。",
  "schema": {
    "type": "string"
  }
}
retryAfter
{
  "description": "距下一个速率限制窗口的秒数。",
  "schema": {
    "type": "integer"
  }
}

responses

Unauthorized
{
  "description": "产品密钥缺失、格式错误、未知、过期或已撤销。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Forbidden
{
  "description": "密钥缺少所需作用域,或资源属于另一个工作区。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
PaymentRequired
{
  "description": "权益问题(订阅未激活、试用已过期、账号/席位/存储限制)。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
NotFound
{
  "description": "资源在调用方的工作区中不存在。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Conflict
{
  "description": "版本/幂等/取消/同意/交付状态冲突。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
Validation
{
  "description": "请求体或目标内容未通过校验。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
RateLimited
{
  "description": "每个工作区的技术速率限制。仅用于限速:绝不是发布配额。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    },
    "Retry-After": {
      "$ref": "#/components/headers/retryAfter"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}
ServerError
{
  "description": "安全的 5XX(提供方不可用或意外的内部错误)。绝不包含原始诊断信息。",
  "headers": {
    "x-request-id": {
      "$ref": "#/components/headers/requestId"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

schemas

Error
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message",
        "requestId"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "unauthenticated",
            "forbidden_scope",
            "account_not_allowed",
            "account_limit",
            "seat_limit",
            "storage_limit",
            "subscription_inactive",
            "trial_expired",
            "validation_failed",
            "unsupported_format",
            "consent_required",
            "reconnect_required",
            "destination_identity_changed",
            "revision_conflict",
            "idempotency_conflict",
            "too_late_to_cancel",
            "media_expired",
            "media_deleting",
            "rate_limited",
            "provider_unavailable",
            "submission_unknown",
            "destination_conflict",
            "not_found",
            "internal_error"
          ]
        },
        "message": {
          "type": "string"
        },
        "fieldErrors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "field",
              "code",
              "message"
            ],
            "properties": {
              "field": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "destinationErrors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "accountId",
              "code",
              "message"
            ],
            "properties": {
              "accountId": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "retryable": {
          "type": "boolean"
        },
        "retryAfterSeconds": {
          "type": "integer"
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Machine-readable extras, e.g. currentVersion for revision_conflict."
        },
        "requestId": {
          "type": "string"
        },
        "requiresAction": {
          "type": "object",
          "description": "Session UI handoff for human consent; never contains credentials or grants access.",
          "required": [
            "type",
            "url",
            "accountIds"
          ],
          "properties": {
            "type": {
              "type": "string",
              "const": "human_consent"
            },
            "url": {
              "type": "string",
              "format": "uri-reference"
            },
            "accountIds": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "workspaceId": {
              "type": "string",
              "format": "uuid",
              "description": "Verified key workspace; the browser must verify membership before switching its selected workspace."
            }
          }
        }
      }
    }
  }
}
Account
{
  "type": "object",
  "required": [
    "id",
    "network",
    "destinationType",
    "displayName",
    "connectionState"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "network": {
      "type": "string",
      "example": "instagram"
    },
    "destinationType": {
      "type": "string",
      "example": "professional_account"
    },
    "displayName": {
      "type": "string"
    },
    "connectionState": {
      "type": "string",
      "example": "connected"
    },
    "capabilityVersion": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
Capability
{
  "type": "object",
  "required": [
    "accountId",
    "network"
  ],
  "properties": {
    "accountId": {
      "type": "string"
    },
    "network": {
      "type": "string"
    },
    "networkEnabled": {
      "type": "boolean"
    },
    "accountConnected": {
      "type": "boolean"
    },
    "capabilityVersion": {
      "type": [
        "string",
        "null"
      ]
    },
    "formats": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "text",
              "single_image",
              "image_set",
              "video"
            ]
          },
          "maxMediaCount": {
            "type": "integer"
          },
          "maxBytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "requiredFields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "eligibleVisibility": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requiresActionReasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "verifiedAt": {
      "type": "string"
    }
  }
}
UploadIntentRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "filename",
    "declaredMime",
    "declaredBytes"
  ],
  "properties": {
    "filename": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "declaredMime": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "example": "image/jpeg"
    },
    "declaredBytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 524288000
    },
    "width": {
      "type": "number",
      "minimum": 0
    },
    "height": {
      "type": "number",
      "minimum": 0
    },
    "durationMs": {
      "type": "number",
      "minimum": 0
    }
  }
}
UploadIntent
{
  "type": "object",
  "required": [
    "assetId",
    "sessionId",
    "objectKey",
    "method",
    "expiresAt",
    "maxBytes"
  ],
  "description": "低于 50 MB 的文件返回 `method: presigned_put`,带短时效的 `uploadUrl` 和所需的 `headers`。达到或超过 50 MB 的文件返回 `method: multipart_initiated`,带 `partSizeBytes` 和由预签名分片 URL 组成的 `parts` 数组;上传每个分片,然后用每个分片的 ETag 回执完成(finalize)。\n",
  "properties": {
    "assetId": {
      "type": "string",
      "format": "uuid"
    },
    "sessionId": {
      "type": "string"
    },
    "objectKey": {
      "type": "string",
      "description": "Opaque storage key; never a public URL"
    },
    "method": {
      "type": "string",
      "enum": [
        "presigned_put",
        "multipart_initiated"
      ]
    },
    "uploadUrl": {
      "type": "string",
      "description": "Short-lived; upload bytes directly with the documented method"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "Required request headers for the presigned PUT (e.g. content-type)"
    },
    "partSizeBytes": {
      "type": "integer",
      "description": "Required part size for multipart uploads"
    },
    "parts": {
      "type": "array",
      "description": "Presigned part URLs (multipart_initiated only); request fresh pages when they expire",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "partNumber",
          "url",
          "expiresAt"
        ],
        "properties": {
          "partNumber": {
            "type": "integer",
            "minimum": 1
          },
          "url": {
            "type": "string"
          },
          "expiresAt": {
            "type": "string"
          }
        }
      }
    },
    "expiresAt": {
      "type": "string"
    },
    "maxBytes": {
      "type": "integer"
    }
  }
}
UploadIntentResponse
{
  "allOf": [
    {
      "$ref": "#/components/schemas/UploadIntent"
    },
    {
      "type": "object",
      "required": [
        "requestId"
      ],
      "properties": {
        "requestId": {
          "type": "string"
        }
      }
    }
  ]
}
TikTokCreatorSettings
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "privacyLevels",
    "maxDurationSeconds",
    "allowComments",
    "allowDuet",
    "allowStitch",
    "directPublishingAllowed",
    "inboxAllowed",
    "nativeAccountId"
  ],
  "properties": {
    "privacyLevels": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "PUBLIC_TO_EVERYONE",
          "MUTUAL_FOLLOW_FRIENDS",
          "FOLLOWER_OF_CREATOR",
          "SELF_ONLY"
        ]
      }
    },
    "maxDurationSeconds": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "allowComments": {
      "type": "boolean"
    },
    "allowDuet": {
      "type": "boolean"
    },
    "allowStitch": {
      "type": "boolean"
    },
    "directPublishingAllowed": {
      "type": "boolean"
    },
    "inboxAllowed": {
      "type": "boolean"
    },
    "nativeAccountId": {
      "type": "string"
    },
    "creatorName": {
      "type": "string"
    },
    "creatorAvatarUrl": {
      "type": "string",
      "format": "uri"
    }
  }
}
MediaStatus
{
  "type": "object",
  "required": [
    "id",
    "originalName",
    "mimeType",
    "bytes",
    "uploadState",
    "createdAt",
    "deletionState"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "originalName": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "uploadState": {
      "type": "string",
      "enum": [
        "pending",
        "uploading",
        "finalized",
        "rejected"
      ]
    },
    "createdAt": {
      "type": "string"
    },
    "deleteAfter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Dynamic deletion date, or null while kept for scheduled posts."
    },
    "deletionState": {
      "type": "string",
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    }
  }
}
FinalizeRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "sessionId"
  ],
  "description": "不接受调用方权威的观察事实(字节/MIME/校验和):服务器自行检查不可变的最终副本。multipart 上传必须包含每个分片的 ETag 回执。\n",
  "properties": {
    "sessionId": {
      "type": "string",
      "format": "uuid"
    },
    "multipart": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "parts"
      ],
      "properties": {
        "parts": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "partNumber",
              "etag"
            ],
            "properties": {
              "partNumber": {
                "type": "integer",
                "minimum": 1
              },
              "etag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            }
          }
        }
      }
    }
  }
}
FinalizeResult
{
  "type": "object",
  "required": [
    "assetId",
    "finalizeOperationId",
    "bytes"
  ],
  "properties": {
    "assetId": {
      "type": "string",
      "format": "uuid"
    },
    "finalizeOperationId": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}
DraftInput
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "caption",
    "destinations"
  ],
  "properties": {
    "caption": {
      "type": "string",
      "maxLength": 70000
    },
    "mediaIds": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "default": []
    },
    "brandFolderId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "default": null
    },
    "destinations": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "items": {
        "$ref": "#/components/schemas/DraftDestination"
      }
    }
  }
}
DraftDestination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "accountId",
    "format"
  ],
  "properties": {
    "accountId": {
      "type": "string",
      "format": "uuid"
    },
    "format": {
      "type": "string",
      "enum": [
        "text",
        "single_image",
        "image_set",
        "video"
      ]
    },
    "overrides": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "caption": {
          "type": "string"
        },
        "mediaIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "title": {
          "type": "string"
        },
        "options": {
          "type": "object",
          "additionalProperties": true,
          "description": "Validated against an allowlisted per-network schema; never a raw vendor bag."
        }
      }
    }
  }
}
DraftUpdateInput
{
  "allOf": [
    {
      "$ref": "#/components/schemas/DraftInput"
    },
    {
      "type": "object",
      "required": [
        "expectedVersion"
      ],
      "properties": {
        "expectedVersion": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  ]
}
DraftSaveResult
{
  "type": "object",
  "required": [
    "postId",
    "version",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "postId": {
      "type": "string",
      "format": "uuid"
    },
    "version": {
      "type": "integer"
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}
PostListItem
{
  "type": "object",
  "required": [
    "postId",
    "version",
    "status",
    "updatedAt"
  ],
  "properties": {
    "postId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "status": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  }
}
ValidationResult
{
  "type": "object",
  "required": [
    "valid",
    "revisionVersion",
    "destinationResults"
  ],
  "properties": {
    "valid": {
      "type": "boolean"
    },
    "revisionVersion": {
      "type": "integer"
    },
    "destinationResults": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "accountId",
          "valid",
          "requiresAction"
        ],
        "properties": {
          "accountId": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "requiresAction": {
            "type": "boolean",
            "description": "True when the network requires an explicit human/consent step."
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}
AcceptedOperation
{
  "type": "object",
  "required": [
    "revisionId",
    "version",
    "operationId",
    "deliveryIds",
    "scheduledAt",
    "timezone",
    "requestId"
  ],
  "properties": {
    "revisionId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "operationId": {
      "type": "string"
    },
    "deliveryIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "scheduledAt": {
      "type": "string"
    },
    "timezone": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "warnings": {
      "type": "array",
      "description": "Non-blocking notices preserved on replay, including key_expires_before_schedule when a key expires at or before dispatch.",
      "items": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
ScheduleRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "scheduledAt",
    "timezone",
    "expectedVersion"
  ],
  "properties": {
    "scheduledAt": {
      "type": "string",
      "format": "date-time",
      "example": "2027-01-12T15:00:00Z"
    },
    "timezone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "example": "America/Indiana/Indianapolis"
    },
    "expectedVersion": {
      "type": "integer",
      "minimum": 1
    },
    "revisionId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Must be null in V1 (schedules the current revision); non-null is rejected."
    }
  }
}
PostStatus
{
  "type": "object",
  "required": [
    "postId",
    "version",
    "status",
    "deliveries"
  ],
  "properties": {
    "postId": {
      "type": "string"
    },
    "version": {
      "type": "integer"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "scheduled",
        "in_progress",
        "published",
        "partially_published",
        "needs_attention",
        "canceled"
      ]
    },
    "deliveries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "accountId": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "dueAt": {
            "type": "string"
          },
          "nativePostUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only after a confirmed result."
          },
          "unresolvedExternalOutcome": {
            "type": "boolean"
          },
          "cancelRequestedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "retryCount": {
            "type": "integer"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}
Usage
{
  "type": "object",
  "description": "此 schema 中任何地方都不存在剩余发布计数器:每个付费套餐的发布量都不限。活动数字是运营指标。\n",
  "required": [
    "plan",
    "accounts",
    "members",
    "storage",
    "scheduling",
    "rateLimit",
    "activity"
  ],
  "properties": {
    "plan": {
      "type": "object",
      "required": [
        "id",
        "label",
        "status"
      ],
      "properties": {
        "id": {
          "type": "string",
          "enum": [
            "trial",
            "creator",
            "studio",
            "operator"
          ]
        },
        "label": {
          "type": "string"
        },
        "version": {
          "type": "integer"
        },
        "interval": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "month",
            "year",
            null
          ]
        },
        "status": {
          "type": "string"
        },
        "paidThrough": {
          "type": [
            "string",
            "null"
          ]
        },
        "trialEndsAt": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "accounts": {
      "type": "object",
      "required": [
        "connected",
        "reserved",
        "maxConnected"
      ],
      "properties": {
        "connected": {
          "type": "integer"
        },
        "reserved": {
          "type": "integer"
        },
        "maxConnected": {
          "type": "integer"
        }
      }
    },
    "members": {
      "type": "object",
      "required": [
        "active",
        "max"
      ],
      "properties": {
        "active": {
          "type": "integer"
        },
        "max": {
          "type": "integer"
        }
      }
    },
    "storage": {
      "type": "object",
      "required": [
        "activeBytes",
        "reservedBytes",
        "maxActiveBytes"
      ],
      "properties": {
        "activeBytes": {
          "type": "integer"
        },
        "reservedBytes": {
          "type": "integer"
        },
        "maxActiveBytes": {
          "type": "integer"
        }
      }
    },
    "scheduling": {
      "type": "object",
      "required": [
        "horizonDays"
      ],
      "properties": {
        "horizonDays": {
          "type": "integer",
          "example": 90
        }
      }
    },
    "rateLimit": {
      "type": "object",
      "required": [
        "requestsPerMinute",
        "note"
      ],
      "properties": {
        "requestsPerMinute": {
          "type": "integer",
          "example": 120
        },
        "note": {
          "type": "string",
          "example": "Technical speed limit: not a posting allowance."
        }
      }
    },
    "activity": {
      "type": "object",
      "description": "Operational metrics only; never an allowance or balance.",
      "required": [
        "deliveriesAttemptedLast30Days",
        "deliveriesPublishedLast30Days"
      ],
      "properties": {
        "deliveriesAttemptedLast30Days": {
          "type": "integer"
        },
        "deliveriesPublishedLast30Days": {
          "type": "integer"
        }
      }
    }
  }
}
CreateWebhookRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "example": "https://example.com/hooks/autoposted"
    },
    "eventTypes": {
      "oneOf": [
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Omit or \"all\" for every event; an array filters by event type."
    },
    "description": {
      "type": "string"
    }
  }
}
WebhookEndpoint
{
  "type": "object",
  "required": [
    "id",
    "url",
    "eventTypes",
    "enabled",
    "createdAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "url": {
      "type": "string",
      "format": "uri"
    },
    "eventTypes": {
      "oneOf": [
        {
          "type": "string",
          "const": "all"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "enabled": {
      "type": "boolean"
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "type": "string"
    }
  }
}