# AssetPipe

AssetPipe gives AI agents real, free-to-use images for websites and documents: search by keyword, fetch a stable hosted URL, and embed with ready-made HTML.

https://assetpipe-production.up.railway.app

## Endpoints

### GET /search?q={keywords}&count={n}

Searches free-to-use photos. Returns a list of results, each with an `asset_id` you use in the next step. `count` is optional (default 5, max 20).

Example call:

```bash
curl "https://assetpipe-production.up.railway.app/search?q=coffee%20shop&count=3"
```

Example response:

```json
{
  "query": "coffee shop",
  "count": 3,
  "results": [
    {
      "asset_id": "px_1284012",
      "preview": "https://cdn.pixabay.com/photo/.../preview.jpg",
      "description": "coffee, shop, interior",
      "width": 1920,
      "height": 1280,
      "license": "free to use, no attribution required (Pixabay Content License)"
    }
  ],
  "next_step": "POST /fetch with an asset_id to get a stable usable URL"
}
```

### POST /fetch

Downloads the chosen image into AssetPipe and returns a stable URL plus ready-to-paste embed HTML and Markdown. Body fields: `asset_id` (required, from /search), `size` (optional: "small", "medium", or "large"; default "medium").

Example call:

```bash
curl -X POST "https://assetpipe-production.up.railway.app/fetch" \
  -H "Content-Type: application/json" \
  -d '{"asset_id": "px_1284012", "size": "medium"}'
```

Example response:

```json
{
  "url": "https://assetpipe-production.up.railway.app/asset/px_1284012_medium.jpg",
  "embed_html": "<img src=\"https://assetpipe-production.up.railway.app/asset/px_1284012_medium.jpg\" alt=\"coffee, shop, interior\" loading=\"lazy\">",
  "embed_markdown": "![coffee, shop, interior](https://assetpipe-production.up.railway.app/asset/px_1284012_medium.jpg)",
  "license": "free to use, no attribution required (Pixabay Content License)"
}
```

### GET /asset/{filename}

Serves the stored image file. The URL returned by /fetch points here. It is stable and safe to hotlink in websites the agent builds.

Example call:

```bash
curl -o asset.jpg "https://assetpipe-production.up.railway.app/asset/px_1284012_medium.jpg"
```

Example response: downloads the image file with HTTP 200 and `Content-Type: image/jpeg`.

## How an agent should use this service

1. Call GET /search with keywords describing the image you need (for example "mountain landscape").
2. Read the results and choose one `asset_id`, using `description`, `width`, and `height` to pick the best match.
3. Call POST /fetch with that `asset_id` and your preferred `size`.
4. Take `embed_html` (for HTML pages) or `embed_markdown` (for Markdown documents) from the response and paste it directly into the content you are creating. The `url` is stable; no attribution is required.
5. Repeat from step 1 for each additional image you need.