> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # 获取任务状态 > 查询 3D 任务执行状态并获取生成的模型文件 # 获取任务状态 查询 3D 生成任务的执行状态，并在完成后获取生成的模型文件。 ## 接口 ```http theme={"dark"} GET https://api.poyo.ai/api/generate/status/{task_id} ``` ## 认证 所有请求都需要 Bearer token 认证： ```bash theme={"dark"} Authorization: Bearer YOUR_API_KEY ``` ## 参数 ### 路径参数 | 参数 | 类型 | 必填 | 说明 | | - | - | - | - | | `task_id` | string | 是 | 提交接口返回的唯一任务标识 | ## 响应 ### 成功响应（200） ```json theme={"dark"} { "code": 200, "data": { "task_id": "9OTM0HH9LBS63LF0", "status": "finished", "credits_amount": 30, "files": [ { "file_url": "https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb", "file_type": "3d" }, { "file_url": "https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_2.png", "file_type": "image" }, { "file_url": "https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_3.glb", "file_type": "3d" } ], "created_time": "2026-05-12T02:36:12", "progress": 100 } } ``` ### 响应字段 | 字段 | 类型 | 说明 | | - | - | - | | `code` | integer | HTTP 状态码（成功为 200） | | `data.task_id` | string | 唯一任务标识 | | `data.status` | string | 任务状态：`not_started`、`running`、`finished`、`failed` | | `data.credits_amount` | number | 该任务扣除的积分 | | `data.files` | array | 状态为 `finished` 时生成的 3D 模型、预览图和配套文件 | | `data.files[].label` | string | 可选的文件标签，例如 `model_glb`、`thumbnail`、模型格式标签、贴图标签或动画标签 | | `data.files[].file_url` | string | 生成文件的直链 URL | | `data.files[].file_type` | string | 生成文件的类型：`3d`、`image` 或 `other` | | `data.files[].format` | string | 可选的文件格式，例如 `glb`、`fbx`、`obj`、`usdz`、`stl` 或 `png` | | `data.files[].content_type` | string | 可选，生成文件的 MIME 类型 | | `data.files[].file_name` | string | 可选，文件名 | | `data.files[].file_size` | integer | 可选，文件大小（字节） | | `data.created_time` | string | 任务创建时间，ISO 8601 格式 | | `data.progress` | number | 完成百分比（0-100） | | `data.error_message` | string | 状态为 `failed` 时的错误说明；成功的任务不返回该字段 | ### 状态值 | 状态 | 说明 | | - | - | | `not_started` | 任务已排队，等待处理 | | `running` | 任务正在生成中 | | `finished` | 任务成功完成，结果在 `files` 中 | | `failed` | 任务失败，错误详情在 `error_message` 中 | ## 代码示例 ```bash theme={"dark"} curl -X GET https://api.poyo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## 重要说明 > [!WARNING] > > **内容有效期**：生成的 3D 文件在创建后 **3 天**内可访问。请及时下载并保存内容。 > [!TIP] > > **Webhook**：除了轮询，你还可以在提交任务时提供 `callback_url` 来自动接收通知。参见[3D Webhook 回调](https://docs.poyo.ai/zh/api-manual/task-management/3d-webhooks.md)。 ## OpenAPI ````yaml zh/api-manual/task-management/3d-status.json GET /api/generate/status/{task_id} openapi: 3.1.0 info: title: PoYo AI - 3D 任务状态 API description: 查询 3D 任务执行状态并获取生成的模型文件 version: 1.0.0 servers: - url: https://api.poyo.ai security: - BearerAuth: [] paths: /api/generate/status/{task_id}: get: tags: - 3D Task Management summary: 查询 3D 任务状态 operationId: queryThreeDTaskStatus parameters: - name: task_id in: path required: true schema: type: string description: 提交接口返回的唯一任务标识 responses: '200': description: 任务状态 content: application/json: schema: $ref: '#/components/schemas/StatusResponse' examples: finished: summary: 已完成的 3D 任务 value: code: 200 data: task_id: 9OTM0HH9LBS63LF0 status: finished credits_amount: 30 files: - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb file_type: 3d - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_2.png file_type: image - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_3.glb file_type: 3d created_time: '2026-05-12T02:36:12' progress: 100 components: schemas: StatusResponse: type: object required: - code - data properties: code: type: integer example: 200 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 data: $ref: '#/components/schemas/TaskStatus' example: code: 200 data: task_id: 9OTM0HH9LBS63LF0 status: finished credits_amount: 30 files: - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb file_type: 3d - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_2.png file_type: image - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_3.glb file_type: 3d created_time: '2026-05-12T02:36:12' progress: 100 TaskStatus: type: object properties: task_id: type: string status: type: string enum: - not_started - running - finished - failed example: finished description: |- 任务状态。 - `not_started`：排队中，等待处理 - `running`：生成中 - `finished`：已完成，结果在 `files` 或 `output` 中 - `failed`：失败，详情见 `error_message` credits_amount: type: number description: 任务消耗的积分 example: 30 files: type: array items: $ref: '#/components/schemas/FileItem' created_time: type: string format: date-time progress: type: number example: 100 error_message: type: - string - 'null' example: task_id: 9OTM0HH9LBS63LF0 status: finished credits_amount: 30 files: - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb file_type: 3d - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_2.png file_type: image - file_url: >- https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_3.glb file_type: 3d created_time: '2026-05-12T02:36:12' progress: 100 FileItem: type: object required: - file_url - file_type properties: label: type: string description: 模型提供时返回的可选文件标签 file_url: type: string format: uri example: https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb file_type: type: string enum: - 3d - image - other example: 3d format: type: string description: 模型提供时返回的可选文件格式 content_type: type: string description: 模型提供时返回的可选 MIME 类型 file_name: type: string description: 模型提供时返回的可选文件名 file_size: type: integer description: 模型提供时返回的可选文件大小（字节） example: file_url: https://cdn.doculator.org/3d/9OTM0HH9LBS63LF0/9OTM0HH9LBS63LF0_1.glb file_type: 3d securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- 所有 API 接口都需要 Bearer Token 认证。 创建 API Key：登录 PoYo，进入 **仪表盘 → API 密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建 Key。 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.