meta_ads_creatives_create
Create a single image or video Meta Ads ad creative, returning the new creative ID and object story ID. Videos require a thumbnail and call-to-action.
Instructions
Creates a single image or video Meta Ads AdCreative. Returns the new creative's id and object_story_id. Mutating — not automatically reversible; record before-state with mureo_state_action_log_append if you may need to roll back. Image mode: supply exactly one of image_url or image_hash — image_url triggers Meta to fetch and host the image; image_hash references an image already uploaded via meta_ads_creatives_upload_image or meta_ads_images_upload_file. Video mode: supply video_id plus exactly one of video_thumbnail_image_hash / video_thumbnail_image_url — Meta requires a thumbnail on every video creative. The video must already be fully processed: poll meta_ads_videos_get until status.video_status reports ready (typically a few minutes after upload), and pick a thumbnail via meta_ads_videos_thumbnails. Video and image parameters are mutually exclusive. Video mode also REQUIRES call_to_action: Meta's video_data has no link field, so the destination is carried inside the CTA and a video creative without one is rejected. For multi-image carousels use meta_ads_creatives_create_carousel; for dynamic / automatic optimization use meta_ads_creatives_create_dynamic.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Creative name shown in Ads Manager. Internal label — not visible to end users. | |
| message | No | Primary ad body text shown above the image or video. Plain text, emoji allowed. Meta recommends ≤125 characters to avoid truncation on mobile. | |
| page_id | Yes | Facebook Page ID that the ad will be published as. Must be a page the authenticated user has permission to post from. Required by Meta for every creative — ads cannot run without a page identity. | |
| headline | No | Headline shown below the media. ~40 characters fits most placements without truncation. Maps to link_data.name in image mode and video_data.title in video mode. | |
| link_url | Yes | Destination URL the ad links to when tapped. Must be HTTPS and domain-verified on the ad account. | |
| video_id | No | Pre-uploaded video ID from meta_ads_videos_upload / meta_ads_videos_upload_file. Switches the creative to video mode (object_story_spec.video_data). The video must be fully processed first — poll meta_ads_videos_get. Mutually exclusive with image_url / image_hash. Setting it makes two otherwise-optional parameters mandatory: one of the video_thumbnail_image_* parameters, and call_to_action. | |
| image_url | No | Public HTTPS image URL. Meta fetches and hosts the asset. Mutually exclusive with image_hash — supply exactly one of them. | |
| account_id | No | Meta Ads account ID in the format 'act_XXXXXXXXXX' (e.g. 'act_1234567890'). Optional — falls back to META_ADS_ACCOUNT_ID from the configured credentials. The leading 'act_' prefix is required. | |
| image_hash | No | Image hash returned from meta_ads_creatives_upload_image / meta_ads_images_upload_file. Mutually exclusive with image_url. | |
| description | No | Description / link-caption text shown below the headline. Optional; not all placements render it. Maps to link_data.description in image mode and video_data.link_description in video mode. | |
| call_to_action | No | Call-to-action button label. Valid values include LEARN_MORE, SIGN_UP, SHOP_NOW, DOWNLOAD, CONTACT_US, SUBSCRIBE, GET_QUOTE, BOOK_TRAVEL, APPLY_NOW. Omit to render no button (link tap still works). The valid set depends on the parent campaign's objective. REQUIRED when video_id is set: the destination link is carried inside this button (video_data.call_to_action.value.link) because Meta's video_data has no link field of its own. link_url is filled in there automatically — pass only the button label. | |
| video_thumbnail_image_url | No | Thumbnail image URL for the video creative — typically a uri from meta_ads_videos_thumbnails (prefer the entry flagged is_preferred). Requires video_id; mutually exclusive with video_thumbnail_image_hash. | |
| video_thumbnail_image_hash | No | Thumbnail image hash for the video creative, from meta_ads_creatives_upload_image / meta_ads_images_upload_file. Requires video_id; mutually exclusive with video_thumbnail_image_url. |