Class: TiktokBusinessApi::Resources::Image

Inherits:
BaseResource show all
Defined in:
lib/tiktok_business_api/resources/image.rb

Overview

Image resource for the TikTok Business API

Instance Attribute Summary

Attributes inherited from BaseResource

#client

Instance Method Summary collapse

Methods inherited from BaseResource

#_http_get, #_http_post, #api_version, #base_path, #initialize, #paginate

Constructor Details

This class inherits a constructor from TiktokBusinessApi::Resources::BaseResource

Instance Method Details

#check_name(advertiser_id, file_names) ⇒ Hash

Check if an image file name is already in use

Parameters:

  • advertiser_id (String) —

    Advertiser ID

  • file_names (Array<String>) —

    List of file names to check

Returns:

  • (Hash) —

    Result with available and unavailable file names



140
141
142
143
144
145
146
147
148
 
# File 'lib/tiktok_business_api/resources/image.rb', line 140

def check_name(advertiser_id, file_names)
  params = {
    advertiser_id: advertiser_id,
    file_names: file_names
  }

  response = client.request(:post, 'file/name/check/', params)
  response['data']
end

#get_info(advertiser_id, image_id) ⇒ Hash

Get image info by image ID

Parameters:

  • advertiser_id (String) —

    Advertiser ID

  • image_id (String) —

    Image ID

Returns:

  • (Hash) —

    Image info



77
78
79
80
81
82
83
84
85
86
 
# File 'lib/tiktok_business_api/resources/image.rb', line 77

def get_info(advertiser_id, image_id)
  params = {
    advertiser_id: advertiser_id,
    image_ids: [image_id]
  }

  response = client.request(:get, "#{base_path}/info/", params)
  images = response.dig('data', 'list') || []
  images.first
end

#resource_name ⇒ String

Get the resource name (used for endpoint paths)

Returns:

  • (String) —

    Resource name



10
11
12
 
# File 'lib/tiktok_business_api/resources/image.rb', line 10

def resource_name
  'file/image/ad'
end

#search(advertiser_id:, **options) {|image| ... } ⇒ Hash, Array

Search for images

Parameters:

  • advertiser_id (String) —

    Advertiser ID

  • options (Hash) —

    Search options

Options Hash (**options):

  • :page (Integer) —

    Current page number (default: 1)

  • :page_size (Integer) —

    Page size (default: 20)

  • :image_ids (String) —

    Image IDs, comma-separated

  • :material_ids (String) —

    Material IDs, comma-separated

  • :width (Integer) —

    Image width

  • :height (Integer) —

    Image height

  • :signature (String) —

    Image MD5 hash

  • :start_time (Integer) —

    Start time, in seconds

  • :end_time (Integer) —

    End time, in seconds

  • :displayable (Boolean) —

    Whether image can be displayed

Yields:

  • (image) —

    Block to process each image

Yield Parameters:

  • image (Hash) —

    Image data from the response

Returns:

  • (Hash, Array) —

    Image list response or processed images



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/tiktok_business_api/resources/image.rb', line 105

def search(advertiser_id:, **options)
  # Set up default values
  page = options[:page] || 1
  page_size = options[:page_size] || 20

  params = {
    advertiser_id: advertiser_id,
    page: page,
    page_size: page_size
  }

  # Add optional parameters if provided
  search_fields = [:image_ids, :material_ids, :width, :height, :signature,
                   :start_time, :end_time, :displayable]

  search_fields.each do |field|
    params[field] = options[field] if options.key?(field)
  end

  response = client.request(:get, "#{base_path}/search/", params)
  image_list = response.dig('data', 'list') || []

  if block_given?
    image_list.each { |image| yield(image) }
    response['data']
  else
    image_list
  end
end

#upload(advertiser_id:, **options) ⇒ Hash

Upload an image

Parameters:

  • advertiser_id (String) —

    Advertiser ID

  • options (Hash) —

    Upload options

Options Hash (**options):

  • :upload_type (String) —

    Upload type (‘UPLOAD_BY_FILE’, ‘UPLOAD_BY_URL’, ‘UPLOAD_BY_FILE_ID’)

  • :file_name (String) —

    Image file name

  • :image_file (File) —

    Image file (required when upload_type is ‘UPLOAD_BY_FILE’)

  • :image_signature (String) —

    MD5 of image file (optional when upload_type is ‘UPLOAD_BY_FILE’, will be calculated if not provided)

  • :image_url (String) —

    Image URL (required when upload_type is ‘UPLOAD_BY_URL’)

  • :file_id (String) —

    File ID (required when upload_type is ‘UPLOAD_BY_FILE_ID’)

Returns:

  • (Hash) —

    Upload result with image ID



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/tiktok_business_api/resources/image.rb', line 25

def upload(advertiser_id:, **options)
  upload_type = options[:upload_type] || 'UPLOAD_BY_FILE'

  params = {
    advertiser_id: advertiser_id,
    upload_type: upload_type
  }

  # Add file_name if provided
  params[:file_name] = options[:file_name] if options[:file_name]

  case upload_type
  when 'UPLOAD_BY_FILE'
    raise ArgumentError, 'image_file is required for UPLOAD_BY_FILE' unless options[:image_file]

    # Auto-calculate image signature if not provided
    if !options[:image_signature]
      options[:image_signature] = TiktokBusinessApi::Utils.calculate_md5(options[:image_file])
    end

    # Create a FilePart for multipart file upload
    params[:image_file] = Faraday::Multipart::FilePart.new(
      options[:image_file],
      TiktokBusinessApi::Utils.detect_content_type(options[:image_file])
    )
    params[:image_signature] = options[:image_signature]

    # For file uploads, we need to use multipart/form-data
    headers = { 'Content-Type' => 'multipart/form-data' }
    response = client.request(:post, "#{base_path}/upload/", params, headers)
  when 'UPLOAD_BY_URL'
    raise ArgumentError, 'image_url is required for UPLOAD_BY_URL' unless options[:image_url]

    params[:image_url] = options[:image_url]
    response = client.request(:post, "#{base_path}/upload/", params)
  when 'UPLOAD_BY_FILE_ID'
    raise ArgumentError, 'file_id is required for UPLOAD_BY_FILE_ID' unless options[:file_id]

    params[:file_id] = options[:file_id]
    response = client.request(:post, "#{base_path}/upload/", params)
  else
    raise ArgumentError, "Invalid upload_type: #{upload_type}"
  end

  response['data']
end