Bring your own creative
Add an image or a video that you own, register it into the ad account of one advertiser, and keep the files of one ad idea together as a Creative of your Library. 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 library_asset_* tools, the agent adds the file to AdCrunch as an Asset. Then it registers the Asset into the ad account of that advertiser. With the library_creative_* and library_variation_* tools, the agent also keeps the files of one ad idea together in your Library. With the library_placement_* and library_placement_group_* tools, it reads and manages the slots that those files are for.
Four words
This job uses four words of AdCrunch: an Asset, a Registration, a Creative of your Library and a Variation. An Asset belongs to your organization. A Registration puts an Asset in the ad account of one advertiser, and one Asset can have a Registration with each of your advertisers. A Creative of your Library is one ad idea, and each of its Variations holds one Asset: for example the 9:16 video and the square image of one idea. A Variation can also name a Placement, the slot that its cut is for. A Creative of your Library is not the creative of an ad account.
The job, step by step
1. Ask for the Asset
“Add https://example.com/spring-sale.mp4 to AdCrunch.”
The agent calls library_asset_create with the public https URL of the file. AdCrunch creates an Asset at pending, and the call returns at once. In the background, AdCrunch fetches the file from the URL and stores it. The bytes do not pass through the conversation.
2. The agent waits for the Asset to be ready
The agent calls library_asset_get until status is ready. AdCrunch reads the header of the file, and checks its type and its size. A file that passes becomes a ready Asset of your organization. When the file fails, the Asset is failed, and failureCode and failureReason say why. To try again, the agent creates a new Asset.
3. The agent can read the Asset
A ready Asset shows in the Assets of your organization, and library_asset_list lists it.
4. The agent registers the Asset
“Put it in the Acme Meta account.”
The agent calls library_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 library_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 library_asset_list. Each Asset comes with its Registrations.
Keep the files of one ad idea together
One ad idea often needs more than one file: a 9:16 cut for Stories and a square cut for the Feed. A Creative of your Library keeps those files together. Each file is a Variation of the Creative.
“Make a creative called Spring sale with the teaser video and the square banner.”
- The agent calls
library_creative_createwith the name. The Creative has no Variation yet. - The agent finds each Asset with
library_asset_list, and callslibrary_variation_addone time for eachreadyAsset. - The agent reads the Creative with
library_creative_get. Its Variations come with it, each with its Asset.
To change the Creative, the agent renames it with library_creative_update, or removes a Variation with library_variation_remove. The Asset of a Variation never changes: to use another file, the agent removes the Variation and adds a new one. To change the slot of a cut, the agent uses library_variation_update. library_creative_delete deletes the Creative and its Variations. The Assets stay in your Library.
A Creative of your Library changes no ad account. To put a file in an ad account, the agent registers its Asset, as the steps above show.
Name the slot of a cut
A Placement is the slot where a provider shows an ad, for example Meta Stories video. It holds rules that an Asset should hold to fit the slot: size in pixels, ratio, file type, weight, and for a video its length. AdCrunch holds global Placements, and your organization can create its own.
“The teaser video is for Meta Stories.”
- The agent finds the slot with
library_placement_list, and reads its rules withlibrary_placement_get. - The agent names the Placement on a new Variation with
library_variation_add, or on an existing one withlibrary_variation_update. The kind of the Asset must be the type of the Placement. The same call withnullclears the Placement. - The agent reads the Creative with
library_creative_get. Each Variation lists its broken rules. A rule that needs a fact the Asset lacks, such as the width of a file that AdCrunch could not read, shows as unknown.
A broken rule is advice. It never blocks a call, and the agent tells you about it before it builds an ad. The agent names a Placement only when you say which slot the cut is for. One Asset can be in two Variations of a Creative when their Placements differ.
When no global Placement describes the slot, the agent creates a Placement of your organization:
“Create a placement for our partner feed: images, 4:5 or 1:1, at least 600 pixels wide.”
The agent calls library_placement_create with a name, a channel, a type, and the rules. The channel and the type never change. library_placement_update changes the name, the description, or the rules. library_placement_delete deletes a Placement, and a live Variation that names it refuses the delete until the agent clears or changes that Placement. A global Placement is read-only.
A Placement group is a named set of Placements. The agent creates one with library_placement_group_create, and fills it with library_placement_group_add and library_placement_group_remove.
What AdCrunch accepts
| Kind | Types | Largest file |
|---|---|---|
| Image | GIF, JPEG, PNG, WebP | 30 MiB |
| Video | MP4, QuickTime (MOV) | 4 GiB |
AdCrunch checks the stored bytes. AdCrunch deletes a file that fails the check, and the Asset is failed. failureCode holds one of these codes:
too_large: the file is over the limit for its kind.unsupported_type: the bytes are a type that is not in the table. AdCrunch reads the type from the bytes, and aContent-Typeis only a hint.unreadable: the file ends before its header does.source_unreachable: AdCrunch could not fetch the file from the URL.source_length_unknown: the source did not send aContent-Length.
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
| State | What it means | What the agent does |
|---|---|---|
running |
The provider takes or processes the file. | It checks again later with library_asset_get. |
ready |
The file is in the ad account of the advertiser, with the id of the provider. | It can build an ad from the Asset. |
failed |
The Registration failed. failureReason gives the reason. When AdCrunch refused the advertiser, failureCode gives a code. |
It registers the Asset again with library_asset_register. It does not create the Asset again. When failureCode is provider_not_connected or missing_write_access, it asks you to reconnect the provider first. |
library_asset_list shows ready Assets only. library_asset_get answers an Asset in every status: pending, ready or failed. A failed Asset carries failureCode and failureReason. library_asset_register accepts a ready Asset only. It answers asset_not_ready for a pending Asset and asset_failed for a failed Asset.
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 needsmutation:write. - Its own scopes. Each read needs
library:read. The creation of an Asset, the Registration, and each change to a Creative or a Variation needlibrary:write. None of them needsmutation:write, because a file in an ad account changes no delivery. See Auth & scopes. - An Asset that a Variation holds stays. The REST API refuses the delete of an Asset while a live Variation holds it, with
asset_in_use. The delete of a Creative and the remove of a Variation never delete an Asset. - One Asset for each Placement, in a Creative. A second Variation of the same Asset with the same Placement, or with no Placement on both, in one Creative fails with
variation_exists. The same Asset can be in other Creatives. - No second copy in the ad account. While an Asset has a
runningorreadyRegistration with an advertiser, a second Registration with that advertiser fails withalready_registered. When the agent registers again after afailedRegistration, 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 Asset. When the Registration fails, the Asset stays with your organization. The agent registers it again, and does not create the Asset again.
Each failed call carries a code. Errors describes the shape of a failed call. What to expect states the rules that each tool follows, such as which organization your client acts for.
Providers
AdCrunch registers files into the ad accounts 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
library_asset_list: list the Assets of your organization, each with its Registrations.library_asset_get: read one Asset, and the state of each Registration.library_asset_create: create an Asset from the URL of a file.library_asset_create_upload: create an Asset from bytes that the agent holds, and get an upload URL.library_asset_register: register an Asset into the ad account of one advertiser.library_creative_list: list the Creatives of your Library, each with its count of Variations.library_creative_get: read one Creative with its Variations.library_creative_create: create a Creative with no Variation.library_creative_update: rename a Creative.library_creative_delete: delete a Creative and its Variations.library_variation_list: list the next pages of the Variations of a Creative.library_variation_add: add a Variation that holds onereadyAsset.library_variation_update: set or clear the Placement of a Variation.library_variation_remove: remove a Variation. Its Asset stays.library_placement_list: list the global Placements and the Placements of your organization.library_placement_get: read one Placement with its rules.library_placement_create: create a Placement of your organization.library_placement_update: change the name, the description, or the rules of a Placement.library_placement_delete: delete a Placement that no live Variation names.library_placement_group_list: list the Placement groups.library_placement_group_get: read one group with its Placements.library_placement_group_create: create an empty group.library_placement_group_update: rename a group.library_placement_group_delete: delete a group. Its Placements stay.library_placement_group_add: add one Placement to a group.library_placement_group_remove: take one Placement out of a group.