> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter 视频转文字

> 把 X 视频里的语音转成文字。

# Twitter 视频转文字

把 X 视频里的语音转成文字。传入带视频的帖子链接，即可返回纯文本形式的转录内容，以及视频时长（秒）。有了文字稿，视频内容就能检索、能引用：摘出采访片段里的原话、总结产品演示、翻译一段演讲，或者把口播内容放进你对文字帖子已有的分析流程里。

```json theme={"dark"}
{
  "urls": [
    "https://x.com/NASA/status/2119833829389041896"
  ]
}
```

通过 urls 提供带视频的 X 帖子链接，路径格式为 /{用户名}/status/{帖子ID}。每个视频返回语音文字和时长。2 分钟以内的视频按 0.7 积分计费；超过 2 分钟的视频按完整时长每开始一分钟计 4 积分，例如 3 分钟的视频计 12 积分。不含视频的帖子不返回结果，也不扣积分。

## 标准结果字段

任务结果使用下方稳定的 SocQ 字段。系统会统一来源特有的字段名和格式，但不会推断或补充来源未提供的数据。如需缩小返回字段集合，MCP 查询使用 `fields`，Typed 工具使用 `_result_fields`，CLI 使用 `--result-fields`。声明字段的值为 `null` 时仍会保留。

| 字段 | 类型 | 可空 | 说明 |
| - | - | - | - |
| `id` | `string` | 是 | 当前结果项的唯一标识。 |
| `platform` | `string` | 否 | 结果所属的平台，例如 `instagram` 或 `linkedin`。 |
| `resource` | `string` | 否 | 该结果对应的 SocQ 资源，例如 `videos` 或 `comments`。 |
| `type` | `string` | 否 | 结果项的类别，例如 `video`、`post` 或 `comment`。 |
| `url` | `string` | 是 | 结果项的公开访问地址（如可获得）。 |
| `published_at` | `string` | 是 | 源内容的发布时间（如可获得），使用 ISO 8601 格式。 |
| `collected_at` | `string` | 否 | SocQ 采集或处理该结果的时间，使用 ISO 8601 格式。 |
| `text` | `string` | 是 | 音频或视频内容的转录文本。 |
| `language` | `string` | 是 | 转录文本的语言（如可获得）。 |
| `format` | `string` | 是 | 转录结果的表示格式，例如纯文本或带时间片段。 |
| `duration_seconds` | `number` | 是 | 时长，单位为秒。 |

以下示例展示任务完成后的响应格式，具体数据以实际查询结果为准。

## 任务完成响应

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "example-x-post-transcript",
    "status": "succeeded",
    "public_id": "x/post-transcript",
    "result_count": 1,
    "credits_amount": 0.7,
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "schema_id": "transcript",
      "schema_version": "1.0",
      "items": [
        {
          "id": "2119833829389041896",
          "platform": "x",
          "resource": "post-transcript",
          "type": "transcript",
          "url": "https://x.com/NASA/status/2119833829389041896",
          "published_at": null,
          "collected_at": "2026-11-13T10:15:28Z",
          "text": "Welcome to Max Power. NASA lit the fires and hosted a four-day showcase of American excellence in air and space right here at Kennedy Space Center. At Up Summit, government and industry came together to align around the technology that will ensure American leadership across the most demanding and exciting domains: from cars that do not require roads, drones that deliver packages, and spacecraft that bring us closer to the stars. Then, AirDot Show took over the skies, bringing some serious American air power and inspiration to thousands of visitors across the Space Coast. And throughout it all, young people, the next generation, met astronauts, pilots, engineers. They saw the machines shaping our future and got a glimpse of the near-limitless world they will inherit. Max Power was only the beginning. With President Trump, we announced Cape Week: what will become the grandest exposition of aerospace technology the world has ever seen. And it begins in March 2028. America is building a new golden age of exploration and discovery, and now every child will have a front-row seat to the greatest adventure in human history.",
          "language": null,
          "format": "text",
          "duration_seconds": 86.709
        }
      ]
    }
  }
}
```


## OpenAPI

````yaml zh/api-manual/agent-api/agent-api.json POST /v1/x/post-transcript
openapi: 3.1.0
info:
  title: SocQ Agent API 中文版
  version: v1-1fa58609f514
  description: 根据 SocQ 能力目录生成的异步社交数据 API。
servers:
  - url: https://api.socq.ai
security: []
paths:
  /v1/x/post-transcript:
    post:
      tags:
        - x
      summary: Twitter 视频转文字
      description: 把 X 视频里的语音转成文字。
      operationId: socq_x_post_transcript
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              additionalProperties: false
              properties:
                callback_url:
                  type: string
                  format: uri
                  description: 可选的任务完成回调 URL。
                urls:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  description: 带视频的 X 帖子链接，格式为 https://x.com/{用户名}/status/{帖子ID}，至少提供 1 项。
              required:
                - urls
              description: >-
                通过 urls 提供带视频的 X 帖子链接，路径格式为 /{用户名}/status/{帖子ID}。每个视频返回语音文字和时长。2
                分钟以内的视频按 0.7 积分计费；超过 2 分钟的视频按完整时长每开始一分钟计 4 积分，例如 3 分钟的视频计 12
                积分。不含视频的帖子不返回结果，也不扣积分。
      responses:
        '200':
          description: 任务已受理
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSubmitResponse'
        '422':
          description: Input validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentValidationErrorResponse'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    AgentSubmitResponse:
      type: object
      properties:
        code:
          type: integer
          const: 200
          description: HTTP 业务状态码。
        data:
          type: object
          properties:
            task_id:
              type: string
              description: 任务 ID，用于查询任务状态和结果。
            status:
              type: string
              description: 任务当前状态。
            created_time:
              type:
                - string
                - 'null'
              description: 任务创建时间。
          required:
            - task_id
            - status
    AgentValidationErrorResponse:
      type: object
      properties:
        code:
          type: integer
          const: 422
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            details:
              type: object
          required:
            - message
            - type
      required:
        - code
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '使用 `Authorization: Bearer <token>` 请求头进行身份验证。'
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 也可以通过 `x-api-key` 请求头提供 API Key。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.