---
title: "Search stock media"
canonical_url: https://docs.zvid.io/docs/endpoints/search-stock-media/
source: docs/endpoints/search-stock-media.api.mdx
content_revision: 6338386a1dd87e4a
---

# Search stock media

`GET /api/stock/search`

Search Zvid's stock library. Anonymous requests use Free-plan renditions. Optional API-key authentication applies the account's media limits. Use returned URLs and metadata, inspect attribution requirements, and validate before rendering.

## Authentication

This operation also permits an unauthenticated request.
- Option 2: `x-api-key: YOUR_API_KEY` (header). API key for authentication. Create one in your dashboard.
- Option 3: `Authorization: Bearer YOUR_ACCESS_TOKEN`. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.

Create API keys at [app.zvid.io/api-keys](https://app.zvid.io/api-keys). Keep credentials on your server.

## Parameters

| Parameter | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `type` | query | `"image"` / `"video"` / `"gif"` / `"audio"` | Yes |  |
| `query` | query | string | No | Maximum length: `200`. |
| `page` | query | integer | No | Default: `1`. Minimum: `1`. Maximum: `500`. |
| `perPage` | query | integer | No | Default: `24`. Minimum: `1`. Maximum: `60`. |

## Request

The shell examples read credentials from `ZVID_API_KEY` (or `ZVID_ACCESS_TOKEN` for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

This operation does not take a request body.

### Request example

```bash
curl --request GET 'https://api.zvid.io/api/stock/search?type=YOUR_TYPE' \
  --header "x-api-key: $ZVID_API_KEY"
```

## Responses


### HTTP 200

Successful response

Content type: `application/json`.

Required properties: `items`, `page`, `perPage`, `hasMore`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.items` | array of object | Yes |  |
| `response.page` | integer | Yes |  |
| `response.perPage` | integer | Yes |  |
| `response.hasMore` | boolean | Yes |  |
| `response.excludedCount` | integer | No |  |
| `response.message` | string | No |  |
| `response.providerErrors` | object | No |  |

**Nested field: `response.items`**

**Array item: `response.items[]`**

Required properties: `id`, `kind`, `src`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.items[].id` | string | Yes |  |
| `response.items[].kind` | `"image"` / `"video"` / `"gif"` / `"audio"` | Yes |  |
| `response.items[].src` | string | Yes | Media URL to use in a project element. |
| `response.items[].preview` | string | No | Picker thumbnail or preview URL. |
| `response.items[].width` | number | No |  |
| `response.items[].height` | number | No |  |
| `response.items[].duration` | number | No |  |
| `response.items[].description` | string | No |  |
| `response.items[].credit` | object | No |  |

**Nested field: `response.items[].credit`**

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.items[].credit.name` | string | No |  |
| `response.items[].credit.link` | string | No |  |


### HTTP 400

Invalid input or semantic validation error

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes |  |
| `response.message` | string | No |  |
| `response.details` | array of object | No |  |
| `response.planLimits` | object | No | Present on render validation errors; contains the authenticated user's current render limits. |

**Nested field: `response.details`**

**Array item: `response.details[]`**

Unknown properties are rejected. Required properties: `field`, `message`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.details[].field` | string | Yes |  |
| `response.details[].message` | string | Yes |  |


### HTTP 401

Missing or invalid credentials

Content type: `application/json`.

Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 404

Not found for this account

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 500

Server error

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 502

Stock library temporarily unavailable

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


### HTTP 503

Stock library unavailable

Content type: `application/json`.

Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


## Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.


### schema stock search result

**StockSearchResult**


Required properties: `items`, `page`, `perPage`, `hasMore`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `StockSearchResult.items` | array of object | Yes |  |
| `StockSearchResult.page` | integer | Yes |  |
| `StockSearchResult.perPage` | integer | Yes |  |
| `StockSearchResult.hasMore` | boolean | Yes |  |
| `StockSearchResult.excludedCount` | integer | No |  |
| `StockSearchResult.message` | string | No |  |
| `StockSearchResult.providerErrors` | object | No |  |

**Nested field: `StockSearchResult.items`**

**Array item: `StockSearchResult.items[]`**

Required properties: `id`, `kind`, `src`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `StockSearchResult.items[].id` | string | Yes |  |
| `StockSearchResult.items[].kind` | `"image"` / `"video"` / `"gif"` / `"audio"` | Yes |  |
| `StockSearchResult.items[].src` | string | Yes | Media URL to use in a project element. |
| `StockSearchResult.items[].preview` | string | No | Picker thumbnail or preview URL. |
| `StockSearchResult.items[].width` | number | No |  |
| `StockSearchResult.items[].height` | number | No |  |
| `StockSearchResult.items[].duration` | number | No |  |
| `StockSearchResult.items[].description` | string | No |  |
| `StockSearchResult.items[].credit` | object | No |  |

**Nested field: `StockSearchResult.items[].credit`**

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `StockSearchResult.items[].credit.name` | string | No |  |
| `StockSearchResult.items[].credit.link` | string | No |  |


### schema validation error

**ValidationError**


Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ValidationError.error` | string | Yes |  |
| `ValidationError.message` | string | No |  |
| `ValidationError.details` | array of object | No |  |
| `ValidationError.planLimits` | object | No | Present on render validation errors; contains the authenticated user's current render limits. |

**Nested field: `ValidationError.details`**

**Array item: `ValidationError.details[]`**

Unknown properties are rejected. Required properties: `field`, `message`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `ValidationError.details[].field` | string | Yes |  |
| `ValidationError.details[].message` | string | Yes |  |


### schema authentication error

**AuthenticationError**


Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `AuthenticationError.error` | string | Yes | Error type |
| `AuthenticationError.message` | string | No | Human-readable error message |


### schema error

**Error**


Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `Error.error` | string | Yes | Error type |
| `Error.message` | string | No | Human-readable error message |


## Related resources

- [OpenAPI specification](https://docs.zvid.io/openapi.yaml)
- [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json)
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Authentication guide](https://docs.zvid.io/docs/authentication/)