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

# 暂停、恢复、启动或停止训练任务

> 通过暂停、恢复、启动与停止转换来控制训练任务的生命周期。每个操作都返回更新后的任务状态。

PIN 支持对训练任务进行显式生命周期控制。你可以暂停运行中的任务以释放其 GPU 同时保留检查点，恢复已暂停的任务以从最后一个检查点继续，启动已排队或已暂停的任务，或停止任务以进入终态。

## 方法与路径

```http theme={null}
POST /v1/jobs/:id/pause
POST /v1/jobs/:id/resume
POST /v1/jobs/:id/start
POST /v1/jobs/:id/stop
```

## 认证

在 `Authorization` 头中以 Bearer 令牌的形式携带你的 PIN API 令牌或 JWT。

```http theme={null}
Authorization: Bearer <token>
```

## 路径参数

<ParamField path="id" type="string" required>
  任务标识符（例如 `jb_abc123def456`）。
</ParamField>

## 请求体

任何生命周期接口都不需要请求体。

## 请求示例

<CodeGroup>
  ```bash Pause theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/pause" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```

  ```bash Resume theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/resume" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```

  ```bash Start theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/start" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```

  ```bash Stop theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/stop" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```
</CodeGroup>

## 响应

返回标准的 PIN 成功信封，包含更新后的任务状态。

<ResponseField name="code" type="integer" required>
  成功为 `0`，出错为非零值。
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="属性">
    <ResponseField name="job_id" type="string">
      任务标识符。
    </ResponseField>

    <ResponseField name="status" type="string">
      转换后的新任务状态。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  可读消息（成功时为空）。
</ResponseField>

### 响应示例

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "jb_abc123def456",
    "status": "paused"
  },
  "message": ""
}
```

## 转换规则

| 操作       | 允许的前置状态           | 结果                   | 说明                     |
| -------- | ----------------- | -------------------- | ---------------------- |
| `pause`  | `running`         | `paused`             | 释放 GPU，保留检查点。          |
| `resume` | `paused`          | `running` 或 `queued` | 优先在智能体本地恢复；失败则回退为重新入队。 |
| `start`  | `queued`、`paused` | `running` 或 `queued` | 若已在运行则无操作。对于已暂停者等同于恢复。 |
| `stop`   | 任意非终态             | `stopped`            | 终态；不退费。                |

## 错误

| Code | HTTP | 含义                      |
| ---- | ---- | ----------------------- |
| 401  | 401  | 缺失或无效的 Bearer 令牌。       |
| 404  | 404  | 任务不存在或不属于你。             |
| 409  | 409  | 无效的状态转换（例如暂停一个非运行中的任务）。 |
| 500  | 500  | 内部服务器错误。                |