create_ad_creative

Create a new ad creative using an uploaded image hash or video ID.

Supports four creative modes:
- **Simple image/video**: Single image_hash or video_id with object_story_spec
- **Multi-variant copy**: Use plural text params (messages[], headlines[], descriptions[]) to test
  multiple text variants with a single image/video. No optimization_type or is_dynamic_creative needed.
- **Dynamic Creative**: Multiple variants with dynamic_creative_spec (requires is_dynamic_creative on ad set)
- **FLEX/DOF (Advantage+)**: Set optimization_type="DEGREES_OF_FREEDOM" for Meta to auto-optimize
  across all asset combinations without requiring is_dynamic_creative on the ad set

Args:
    account_id: Meta Ads account ID (format: act_XXXXXXXXX)
    image_hash: Hash of a single uploaded image (cannot be used with image_hashes or video_id)
    access_token: Meta API access token (optional - will use cached token if not provided)
    name: Creative name
    page_id: Facebook Page ID (string or int; coerced to string)
    link_url: Destination URL for the ad (required unless using lead_gen_form_id)
    message: Single ad copy/text (cannot be used with messages)
    messages: List of primary text variants for multi-variant copy testing (cannot be used with message)
    headline: Single headline for simple ads (cannot be used with headlines)
    headlines: List of headline variants for multi-variant copy testing (cannot be used with headline)
    description: Single description for simple ads (cannot be used with descriptions)
    descriptions: List of description variants for multi-variant copy testing (cannot be used with description)
    image_hashes: List of image hashes for FLEX creatives (up to 10, cannot be used with image_hash or video_id)
    video_id: Meta video ID for video creatives (cannot be used with image_hash or image_hashes).
              Upload a video first via the Meta API, then use the returned video ID here.
    thumbnail_url: Thumbnail image URL for video creatives. Recommended when using video_id.
                  Meta will auto-generate a thumbnail if not provided.
    optimization_type: Optional. Set to "DEGREES_OF_FREEDOM" for FLEX (Advantage+) creatives that
                      allow Meta to auto-optimize across all asset combinations. Not required for
                      text-only multi-variant creatives (messages[], headlines[], descriptions[]
                      work without it). When using DEGREES_OF_FREEDOM, at least one asset field
                      (image_hashes, messages, headlines, or descriptions) must contain more than
                      one variant.
                      NOTE: If asset_customization_rules is also provided, optimization_type
                      is automatically removed because Meta ignores placement rules for DOF
                      creatives. The creative will use regular dynamic creative mode instead.
    dynamic_creative_spec: Dynamic creative optimization settings
    call_to_action_type: Call to action button type (e.g., 'LEARN_MORE', 'SIGN_UP', 'SHOP_NOW',
                        'CALL_NOW'). When using CALL_NOW, also provide phone_number.
    lead_gen_form_id: Lead generation form ID for lead generation campaigns. Required when using
                     lead generation CTAs like 'SIGN_UP', 'GET_OFFER', 'SUBSCRIBE', etc.
    instagram_actor_id: Instagram account ID for Instagram placements (must be a string
                       to avoid JavaScript integer precision loss for IDs exceeding
                       Number.MAX_SAFE_INTEGER). Sent as instagram_user_id inside
                       object_story_spec (Meta deprecated instagram_actor_id in Jan 2026).
    ad_formats: List of ad format strings for asset_feed_spec (e.g., ["AUTOMATIC_FORMAT"] for
               Flexible ads, ["SINGLE_IMAGE"] for single image, ["SINGLE_VIDEO"] for video).
               When optimization_type is "DEGREES_OF_FREEDOM" with image_hashes, defaults to
               ["AUTOMATIC_FORMAT"] (Flexible format). For video creatives, defaults to
               ["SINGLE_VIDEO"]. Otherwise defaults to ["SINGLE_IMAGE"].
    asset_customization_rules: List of placement-specific asset overrides for asset_feed_spec.
    phone_number: Phone number for CALL_NOW call-to-action ads (click-to-call).
                 Required when call_to_action_type is CALL_NOW. Use E.164 format
                 (e.g., "+18005551234"). The number is passed to Meta in
                 call_to_action.value.phone_number. Common use case: geo-routed
                 call ads with different phone numbers per ad set.
    creative_features_spec: Advantage+ Creative feature opt-ins/opt-outs. Controls individual
               creative enhancements like image_touchups, text_optimizations, inline_comment,
               add_text_overlay, music, 3d_animation, etc. Each feature is a dict with
               "enroll_status" set to "OPT_IN" or "OPT_OUT".
               Example: {"image_touchups": {"enroll_status": "OPT_IN"},
                        "inline_comment": {"enroll_status": "OPT_IN"}}
               Sent to Meta as degrees_of_freedom_spec.creative_features_spec.
    url_tags: URL tracking parameters appended to the destination URL (e.g.,
             "utm_source=facebook&utm_medium=cpc&utm_campaign=spring_sale").
             Sets the url_tags field on the creative.
    caption: Display URL shown in the ad (e.g., "example.com/shoes"). Sets the
            caption field in link_data. If not provided, Meta auto-generates it
            from the destination URL. Only applies to image (link_data) creatives.
    image_crops: Crop coordinates for different aspect ratios. Applied in link_data for
                image creatives.

                Use the compute_image_crops tool first to get the correct coordinates
                for your specific image dimensions — it computes centered crop boxes
                for any source size automatically.

                Valid crop keys (only these 6 are accepted by Meta's API):
                  "100x100"  — 1:1 square (Feed, Marketplace, Search)
                  "100x72"   — ~1.39:1 horizontal (Marketplace, some placements)
                  "400x500"  — 4:5 portrait (Feed on mobile, Stories fallback)
                  "400x150"  — ~2.67:1 wide banner (Audience Network)
                  "600x360"  — ~1.67:1 horizontal (Right column, some placements)
                  "90x160"   — 9:16 tall portrait (Stories)

                Format: {"100x100": [[x1,y1],[x2,y2]], "400x500": [[x1,y1],[x2,y2]]}
                Coordinates are pixel-based (top-left and bottom-right corners).
                The bounding box aspect ratio must match the key ratio as closely as possible.
                Image origin (0,0) is the upper-left corner.

                Omit to let Meta auto-crop (default for horizontal is 1.91:1 recommended).
    asset_customization_rules: Lets you assign different images or videos to specific placement groups
               (e.g., feed vs. stories). Only valid with image_hashes or plural asset params.
               Each rule uses a user-friendly format that is automatically translated to
               Meta's API format (adlabels + customization_spec positions):
                 - placement_groups: list of placement group names
                   Valid values: FEED, STORY, MESSENGER, INSTREAM_VIDEO, SEARCH, SHOP,
                   AUDIENCE_NETWORK
                 - customization_spec: dict specifying the asset to use for those placements
                   Supported keys: image_hashes (list), video_ids (list),
                   bodies, titles, descriptions (text overrides)
               All image hashes referenced in rules must also be in image_hashes.
               Example (feed gets one image, stories gets another):
               [
                 {"placement_groups": ["FEED"],
                  "customization_spec": {"image_hashes": ["<feed_hash>"]}},
                 {"placement_groups": ["STORY"],
                  "customization_spec": {"image_hashes": ["<story_hash>"]}}
               ]

Returns:
    JSON response with created creative details