Bring your own creative

Upload an image or a video that you own, and register it into the provider library of one advertiser, so that an ad there can use it. All from your AI client.

You have an image or a video, and you want an ad of one advertiser to use it. Ask your agent. With the five asset_* tools, the agent uploads the file to AdCrunch as an Asset. Then it registers the Asset into the provider library of that advertiser.

Two words

This job uses two words of AdCrunch: an Asset and a Registration. An Asset belongs to your organization. A Registration puts an Asset in the provider library of one advertiser, and one Asset can have a Registration with each of your advertisers.

The job, step by step

1. Ask for the upload

“Upload spring-sale.mp4 from my Downloads folder to AdCrunch.”

The agent calls asset_create_upload with the name of the file. AdCrunch reserves an Asset and gives the agent an upload URL. The URL is valid for one hour, and it can write this one file only.

2. The agent sends the file

The agent reads the file and sends it to the upload URL, with an HTTP PUT from its own runtime. The file goes straight to storage. It does not pass through the conversation.

3. The agent finalizes the upload

The agent calls asset_finalize. AdCrunch knows nothing about the file until it arrives, so it checks the stored file now. It reads the header of the file, and it checks the bytes against the type that the upload declared. A file that passes becomes a ready Asset of your organization. AdCrunch deletes a file that fails, and the agent tells you why. To try again, the agent starts a new upload.

When you name an advertiser in your request, the agent can start the Registration in the same call.

4. The agent registers the Asset

“Put it in the Acme Meta account.”

The agent calls asset_register with the Asset and the advertiser. The call returns at once, with a running Registration. The provider takes the file in the background.

5. The agent checks until the Registration settles

“Is the video ready in the Acme account yet?”

The agent calls asset_get, and reads the Registration with that advertiser. An image is ready as soon as the provider takes it. A video can stay running for several minutes while the provider processes it. That is normal, and it is not a failure. When the Registration is ready, you see the id that the provider gave the file, and an ad of that advertiser can use the file.

To see the Assets of your organization, ask:

“What creative do we have, and where is each file registered?”

The agent calls asset_list. Each Asset comes with its Registrations.

What AdCrunch accepts

AdCrunch cannot see the file before it arrives, so it checks the stored bytes at finalize. AdCrunch deletes a file that fails the check. The agent then gets one of these codes:

• too_large: the file is over the limit for its kind.
• unsupported_type: the upload declared a type that is not in the table.
• type_mismatch: the bytes are a different type from the type that the upload declared.
• unreadable: the bytes are no accepted type, or the file ends before its header does.

A provider can have lower limits of its own. When the provider refuses a file, the Registration is failed, and the Asset stays with your organization.

The state of a Registration

The tools show a ready Asset only. An upload that never finished does not show in the Assets of your organization.

Guardrails

• A Registration puts nothing live. It makes a file available to an ad of one advertiser. It creates no ad and spends no money. On Meta, the agent builds an ad creative from a registered Asset with meta_create_creative, which needs mutation:write.
• Its own scopes. The two reads need asset:read. The upload, the finalize and the Registration need asset:write. None of them needs mutation:write, because a file in a provider library changes no delivery. See Auth & scopes.
• No copy in the provider library. While an Asset has a running or ready Registration with an advertiser, a second Registration with that advertiser fails with already_registered. When the agent registers again after a failed Registration, AdCrunch replaces the failed one. So a retry is safe.
• Your organization only. An Asset or an advertiser that is not in your organization gives not_found. An id that does not exist gives the same answer, so nobody can find out whether an id is real.
• A failed Registration is not a failed upload. When the Registration fails, the Asset stays with your organization. The agent registers it again, and does not upload the file again.
• The upload URL is a key. Anybody who has the URL can write that one file until the URL expires, one hour after the reservation.

Each failed call carries a code. Errors describes the shape of a failed call.

Providers

AdCrunch registers files into the libraries of Meta and TikTok. Meta takes the bytes from AdCrunch. TikTok fetches the file itself, and applies its own limits to it. What each provider supports states what happens with an advertiser of another provider.

The tools of this job

• asset_list: list the Assets of your organization, each with its Registrations.
• asset_get: read one Asset, and the state of each Registration.
• asset_create_upload: reserve an Asset, and get the upload URL.
• asset_finalize: check the stored file, and make it a ready Asset.
• asset_register: register an Asset into the provider library of one advertiser.