# Search stock media

`GET https://api.vidmoat.com/v1/stock/search`

- Scope: `stock.read`
- Cost: Free

Search the stock library by keyword, then import a result's downloadUrl with /v1/media/import.

### Query parameters

- `query` (string, optional): Keywords. Required for `video` and `image`; for `audio`, empty returns a popular list.
- `type` (enum, optional, default `video`): What to search. One of `video`, `image`, `audio`.
- `limit` (integer, optional, default `12`): 1 to 24.

## Response

Returns `200`.

### Response fields

- `data` (array): Results. Video and image results have `provider`, `id`, `mediaType`, `thumbnailUrl`, `downloadUrl`, `width`, `height`, `duration` (video), `photographer`, `sourceUrl` and licence fields. Audio results (CC0 only) have `id`, `name`, `downloadUrl`, `duration`, `username`, `sourceUrl`, `tags` and `bpm`.
- `hint` (string): What to do with a result.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | `query` is missing for a video or image search. |
| 502 | [`provider_error`](https://developer.vidmoat.com/developer/docs/errors#provider_error) | The search failed. |

## Request examples

```bash curl
curl "https://api.vidmoat.com/v1/stock/search?query=city+at+night&type=video" \
  -H "Authorization: Bearer $VIDMOAT_KEY"
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/stock/search?query=city+at+night&type=video', {
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.get(
    "https://api.vidmoat.com/v1/stock/search?query=city+at+night&type=video",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "data": [{
    "provider": "pexels",
    "id": "123",
    "mediaType": "video",
    "thumbnailUrl": "https://…",
    "downloadUrl": "https://…",
    "width": 1920, "height": 1080, "duration": 12,
    "photographer": "Jane Doe",
    "sourceUrl": "https://www.pexels.com/…"
  }],
  "hint": "Pass a result's downloadUrl to POST /v1/media/import, then use the url that returns as an addClip `src`."
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/media/search-stock
Previous: [Import from a URL](https://developer.vidmoat.com/developer/docs/api/media/import-media.md)
Next: [Transcribe media](https://developer.vidmoat.com/developer/docs/api/generation/create-transcription.md)
All documentation: https://developer.vidmoat.com/llms-full.txt