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. 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
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.
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 |
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 |
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 |
Error
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
Error.error | string | Yes | Error type |
Error.message | string | No | Human-readable error message |