# Direct HTTP API / HTTP 直连接口

Route: /docs/api/direct-http
Updated: 2026-07-08

## English

# Direct HTTP API

Use HTTP when you want to call SorryAssets without opening the desktop app.

## Contract

- Base URL: `https://sorryassets.com`.
- Auth header for spend and task endpoints: `Authorization: Bearer sa_your_key`.
- Discovery endpoints are public: `GET /v1/catalog` and `GET /v1/pricing`.
- Skills are standard Agent Skills packages discovered through the Skills catalog and installed into agent hosts; they are not a custom HTTP manifest API.
- Generation endpoints require an account key: `POST /v1/estimate`, `POST /v1/generate`, `GET /v1/task/:taskRef`.
- Asset delivery: `GET /v1/asset/:taskRef`.

## Flow

1. Discover available capabilities and models.
2. Estimate before spending.
3. Submit a generation task.
4. Poll until the task is terminal.
5. Download the output promptly.

```bash
API_BASE="https://sorryassets.com"
curl "$API_BASE/v1/catalog"
```

```bash
curl -X POST "$API_BASE/v1/estimate" \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "image.generate",
    "provider": "gemini",
    "model": "gemini-3.1-flash-image",
    "params": {
      "inputs": [],
      "values": {
        "prompt": "a product photo of a lime green studio headset",
        "size": "1024x1024"
      }
    }
  }'
```

```bash
CLIENT_EDGE_ID="$(uuidgen)"
curl -X POST "$API_BASE/v1/generate" \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "api-demo",
    "capability": "image.generate",
    "provider": "gemini",
    "model": "gemini-3.1-flash-image",
    "clientEdgeId": "'"$CLIENT_EDGE_ID"'",
    "params": {
      "inputs": [],
      "values": {
        "prompt": "a product photo of a lime green studio headset",
        "size": "1024x1024"
      }
    }
  }'
```

```bash
TASK_REF="sa-task-ref-from-generate"
curl "$API_BASE/v1/task/$TASK_REF" \
  -H "Authorization: Bearer sa_your_key"
```

## Delivery rule

SorryAssets delivers assets, it does not host a cloud library of user generations. The backend never exposes upstream URLs. A successful task returns a SorryAssets `outputUrl` while the upstream content is still available.

Download the output into your own project or pipeline when the task succeeds.

OpenAI-compatible image and video endpoint families are the GA target, not the Developer Preview contract today.

## 中文

# HTTP 直连接口

如果你希望不打开桌面应用，直接从自己的产品、脚本或 Agent 调用 SorryAssets，就使用 HTTP API。

## 契约

- Base URL：`https://sorryassets.com`。
- 消费和任务接口使用鉴权头：`Authorization: Bearer sa_your_key`。
- 公开发现接口：`GET /v1/catalog`、`GET /v1/pricing`。
- Skills 使用标准 Agent Skills 包，通过 Skills catalog 发现并安装到 Agent 宿主，不是 SorryAssets 自创的 HTTP manifest API。
- 账户密钥接口：`POST /v1/estimate`、`POST /v1/generate`、`GET /v1/task/:taskRef`。
- 资产交付：`GET /v1/asset/:taskRef`。

## 调用顺序

1. 读取目录，确认可用能力和模型。
2. 先估价，再消费。
3. 提交生成任务。
4. 轮询到终态。
5. 及时下载产物。

```bash
API_BASE="https://sorryassets.com"
curl "$API_BASE/v1/catalog"
```

```bash
curl -X POST "$API_BASE/v1/estimate" \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "capability": "image.generate",
    "provider": "gemini",
    "model": "gemini-3.1-flash-image",
    "params": {
      "inputs": [],
      "values": {
        "prompt": "a product photo of a lime green studio headset",
        "size": "1024x1024"
      }
    }
  }'
```

```bash
CLIENT_EDGE_ID="$(uuidgen)"
curl -X POST "$API_BASE/v1/generate" \
  -H "Authorization: Bearer sa_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "api-demo",
    "capability": "image.generate",
    "provider": "gemini",
    "model": "gemini-3.1-flash-image",
    "clientEdgeId": "'"$CLIENT_EDGE_ID"'",
    "params": {
      "inputs": [],
      "values": {
        "prompt": "a product photo of a lime green studio headset",
        "size": "1024x1024"
      }
    }
  }'
```

```bash
TASK_REF="sa-task-ref-from-generate"
curl "$API_BASE/v1/task/$TASK_REF" \
  -H "Authorization: Bearer sa_your_key"
```

## 交付规则

SorryAssets 交付资产，不托管用户生成的云端资产库。后端不会暴露上游 URL。任务成功后返回 SorryAssets 的 `outputUrl`，只在上游内容仍可用时代理交付。

任务成功后，请把产物下载到自己的项目或流水线。

OpenAI-compatible image / video 端点族是 GA 目标，不是当前 Developer Preview 契约。