curl --request POST \
--url https://app.bily.ai/api/customer/v1/creative-intelligence/{storeUrl}/uploads \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"idempotencyKey": "<string>",
"fileName": "<string>",
"sizeBytes": 49807360
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({idempotencyKey: '<string>', fileName: '<string>', sizeBytes: 49807360})
};
fetch('https://app.bily.ai/api/customer/v1/creative-intelligence/{storeUrl}/uploads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.bily.ai/api/customer/v1/creative-intelligence/{storeUrl}/uploads"
payload = {
"idempotencyKey": "<string>",
"fileName": "<string>",
"sizeBytes": 49807360
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"upload": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"fileName": "product.png",
"contentType": "image/png",
"sizeBytes": 1024,
"mediaUrl": null,
"expiresAt": 1800000000,
"pinnedAt": null
},
"uploadUrl": "<string>",
"reused": true
}{
"upload": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"fileName": "product.png",
"contentType": "image/png",
"sizeBytes": 1024,
"mediaUrl": null,
"expiresAt": 1800000000,
"pinnedAt": null
},
"uploadUrl": "<string>",
"reused": true
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}Reserve a Creative Reference Upload
Reserve one workspace image or video upload with a stable caller idempotency key. MCP returns a relative first-party PUT path for the declared file; resolve it against the MCP endpoint origin and transfer bytes outside MCP with the same creator’s separately authenticated browser session or Customer API write key and exact content length. An MCP OAuth grant alone cannot authenticate that transfer. The PUT verifies storage and schedules internal paid analysis; finalizeUpload is an idempotent verification/recovery step. MCP does not fetch caller URLs, read local files, return signed storage credentials, or create an ad.
curl --request POST \
--url https://app.bily.ai/api/customer/v1/creative-intelligence/{storeUrl}/uploads \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"idempotencyKey": "<string>",
"fileName": "<string>",
"sizeBytes": 49807360
}
'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({idempotencyKey: '<string>', fileName: '<string>', sizeBytes: 49807360})
};
fetch('https://app.bily.ai/api/customer/v1/creative-intelligence/{storeUrl}/uploads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://app.bily.ai/api/customer/v1/creative-intelligence/{storeUrl}/uploads"
payload = {
"idempotencyKey": "<string>",
"fileName": "<string>",
"sizeBytes": 49807360
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"upload": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"fileName": "product.png",
"contentType": "image/png",
"sizeBytes": 1024,
"mediaUrl": null,
"expiresAt": 1800000000,
"pinnedAt": null
},
"uploadUrl": "<string>",
"reused": true
}{
"upload": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "pending",
"fileName": "product.png",
"contentType": "image/png",
"sizeBytes": 1024,
"mediaUrl": null,
"expiresAt": 1800000000,
"pinnedAt": null
},
"uploadUrl": "<string>",
"reused": true
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}{
"error": "Store not found",
"requestId": "<string>",
"details": "<unknown>",
"retryAfter": "<string>"
}Authorizations
A server-side Bily API key created under Settings > AI tools > Access keys. Select the intended workspace before creating it.
Headers
An organization ID returned by GET /context or GET /organizations. Omit it when a scoped key supplies the organization. Otherwise provide it when no organization is selected.
"org_01J8W7T9G3E6ZQ4M2K5N8P1R0S"
Path Parameters
Exact workspace URL returned by GET /context.
Body
1 - 256^[A-Za-z0-9._~-]+$1 - 240image/jpeg, image/png, image/webp, video/mp4, video/quicktime, video/webm 1 <= x <= 99614720Response
Request completed. Inspect the returned state and any verification fields.