Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 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 variation_* tools, the agent also keeps the files of one ad idea together in your Library.

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 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 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 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 asset_list lists it.

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.

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.”

  1. The agent calls library_creative_create with the name. The Creative has no Variation yet.
  2. The agent finds each Asset with asset_list, and calls variation_add one time for each ready Asset.
  3. 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 variation_remove. A Variation has no update: to use another file, the agent removes the Variation and adds a new one. 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.

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 a Content-Type is 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 a Content-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 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 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.

asset_list shows ready Assets only. asset_get answers an Asset in every status: pending, ready or failed. A failed Asset carries failureCode and failureReason. 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 needs mutation: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 need library:write. None of them needs mutation: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, one Variation, in a Creative. A second Variation of the same Asset 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 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 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

Was this page helpful?