Mockup Generator API

モックアップを生成するには、まずあなたがどの商品をそれらが欲しいかを決める必要があります。 商品やバリアントを取得するためのAPIメソッドは、 印刷可能なカタログAPI

:商品IDとバリアントIDの違いを忘れないでください。いくつかのAPIエンドポイント 要求する バリアントからのIDと商品からのID。

プリントファイル

プリントファイルは、モックアップの作成または実際の注文の送信に使用される解像度を定義します。

商品のバリアントプリントファイルに関する情報は、次のWebサイトから入手できます。 プリントファイルのエンドポイント

たとえば、10×10のポスターに150 DPIの印刷を作成するには、1500×1500ピクセルのプリントファイルが必要です。 より高い解像度のファイルを使用してより良い結果を得ることができますが、側面の縦横比は同じに保ちます。 プリントファイルに定義されているつまり、3000×3000ピクセルのファイルを使用すると、300 DPIの印刷が行われます。 ただし、10×10のポスターに3000×1500ピクセルのファイル(縦横比が異なる)を使用すると、トリミングされます。 起こる。プリントファイルの fill_mode パラメータは、切り取りが行われるかどうかを定義します。 ファイルは、商品の結果の印刷領域に収まります。

一部のプリントファイルプリントファイルは回転できます。 can_rotate フィールドはこの機能を定義します。 これは主にウォールアート商品に適用され、水平または垂直の商品モックアップを生成する場合に使用する必要があります。

ウォールアートプリントファイルは水平方向に定義されています。垂直モックアップを作成したい場合は、ファイルの デザインデータと生成されたモックアップは指定された向きになります。たとえば、16×12ポスタープリントファイルは それを水平に生成する2400×1800ピクセル。あなたが垂直モックアップを取得したい場合は、プリントを作成します 1800×2400ピクセルとしてファイル化します。注文を送信するときにも同じ戦略が適用されます。

プリントファイルは多くの場合、複数の派生物や商品に再利用されます。例えば、14×14のポスターは同じものを使用します。 フレーム付きポスターとしてファイルを印刷します。ほとんどのTシャツのフロントプリントも同じプリントファイルを使用しています。

:モックアップを生成するときは、フルサイズのデザインデータを用意する必要はありません。モックアップが生成されます 最大1000px幅なので、プリントファイルを1000pxに縮小することができます。これはあなたの処理時間を短縮します Printful側に。

モックアップ生成

モックアップ生成にはある程度の時間がかかるため、リアルタイムでは実行できません。

モックアップの生成を要求すると、タスクが作成され、そのタスクキーを受け取ることができます。 生成されたモックアップリストを取得するために使用されます。一定時間経過後にモックアップが発生することを保証することはできません。 生成されるので、タスクが完了したかどうかを頻繁に確認する必要があります。 結果の最初の要求は10秒より早くなるべきではありません。だから世代を先に計画しなさい タスクは2つのステップで実行されます - タスクを作成し、タスクの準備ができていれば間隔を置いてチェックします。

重要です。 モックアップ画像へのURLは一時的なもので、1日後に期限切れになるので、自分のサーバーに保存する必要があります。

プロセスフロー

  1. どの商品バリエーションを生成するかを決めます。

  2. 選択した商品とバリエーションのデザインデータのリストを取得します。バリエーションデザインデータマッピングを使用して、特定の商品のバリエーションの特定の配置に対してどの印刷ファイルを生成する必要があるかを判断します。

  3. デザインデータのサイズの比率と一致するパブリックURLにファイルをアップロードします(または生成要求の位置を指定します)

  4. モックアップ生成タスクを作成し、そのタスクキーを保存します。

  5. タスクキーを使用して、タスクが完了したかどうかを確認します。保留中の場合は間隔をおいて繰り返します。

  6. タスクが完了したら、モックアップをダウンロードして自分のサーバーに保存します。 モックアップURLは一時的なもので、1日後に削除されます。

使用例

例を見てみましょう。ユーザーに自分のTシャツをデザインしてもらいたいのです。

例としてこのシャツを選びます - Bella + Canvas 3001ユニセックスTシャツ

商品IDは 71 です。

このシャツに利用可能ないくつかの亜種を取得しましょう:
https://api.printful.com/products/71

M、L、XLサイズの白と黒のシャツを選びます。それぞれのバリアントID:
4012 4013 4014 4017 4018 4019

次に、これらの亜種のデザインデータサイズを取得する必要があります。
https://api.printful.com/mockup-generator/printfiles/71

この商品には2つのプレースメントがあります - たとえば、ポスターには default という1つのプレースメントしかありません。

弊社が選んだバリアントIDを調べると、裏と表の印刷に同じデザインデータが使用されています。

{
    "product_id": 71,
    "available_placements": {
        "front": "Front print",
        "back": "Back print",
        "label_outside": "Outside label"
    },
    "printfiles": [
        {
            "printfile_id": 1,
            "width": 1800,
            "height": 2400,
            "dpi": 150,
            "fill_mode": "fit",
            "can_rotate": false
        }
    ],
    "variant_printfiles": [
        {
            "variant_id": 4012,
            "placements": {
                "front": 1,
                "back": 1
            }
        }
    ]
}
  • dpi 指定された幅と高さに対し、これは実際の商品のDPIです。

  • fill_mode 可能な値: 「fit」または「cover」。どのモードでモックアップが生成されるかを示します。

  • たとえば、 can_rotate ポスターは回転を許可します。水平位置で画像を渡す場合。

  • placements.front 印刷ファイルID。

選択したバリエーションの裏と表の印刷ののフル印刷ファイルのサイズは1800×2400です。

重要 - これは印刷に使用するデザインデータのサイズです。モックアップ生成の場合、結果のモックアップは1000pxより大きくならないため、画像は1000pxの幅を超えてはいけません。

デザインデータのサイズがわかったら、位置を計算する必要があります。 ここでは位置の値は相対的なものです。画像サイズは位置の幅と高さに一致する必要はありません 。 モックアップが生成されると、デザインデータの fill_mode の値に応じて、位置領域を印刷領域の内側に合わせる、またはそれを覆います。

それよりも下の位置にすると、印刷領域内で垂直方向の中央に正方形の画像が表示されます。

    {
        "area_width": 1800,
        "area_height": 2400,
        "width": 1800,
        "height": 1800,
        "top": 300,
        "left": 0
    }
  • area_width 印刷領域の相対的な幅。

  • area_height 印刷領域の相対的な高さ。

  • width 画像の相対的な幅。

  • height 画像の相対的な高さ。

  • top 領域内の相対的な画像の上部オフセット。

  • left 領域内での相対イメージの左オフセット。

重要 - ポスター、キャンバス、およびデザインデータで回転が可能なその他の商品 ( デザインデータレスポンスの can_rotate 値) 幅と高さを反転して、水平または垂直の商品モックアップを作成できます。

位置を計算したら、次のようにして実際のモックアップ生成を実行できます。 デザイン作成ツールエンドポイント

POST https://api.printful.com/mockup-generator/create-task/71 ボディパラメータを使って行う:

{
    "variant_ids" : [4012, 4013, 4014, 4017, 4018, 4019],
    "format": "jpg",
    "files" : [
        {
            "placement": "front",
            "image_url": "http://your-site/path-to-front-printfile.jpg",
            "position": {
                "area_width": 1800,
                "area_height": 2400,
                "width": 1800,
                "height": 1800,
                "top": 300,
                "left": 0
            }
        },
        {
            "placement": "back",
            "image_url": "http://your-site/path-to-back-printfile.jpg",
            "position": {
                "area_width": 1800,
                "area_height": 2400,
                "width": 1800,
                "height": 1800,
                "top": 300,
                "left": 0
            }
        }
    ]
}

返信として、タスクキーと現在のタスクステータスが表示されます。

{
    "task_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "pending"
}

数秒のインターバルの後で、 GET リクエスト https://api.printful.com/mockup-generator/task?task_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx を呼び出して結果を確認することができます

タスクが完了したら、回答は次のようになります。

{
    "task_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "completed",
    "mockups": [
        {
            "variant_ids": [
                4011,
                4012,
                4013
            ],
            "placement": "front",
            "mockup_url": "https://url-to/front-mockup.png"
        },
        {
            "variant_ids": [
                4011,
                4012,
                4013
            ],
            "placement": "back",
            "mockup_url": "https://url-to/back-mockup.png"
        },
        {
            "variant_ids": [
                4016,
                4017,
                4018
            ],
            "placement": "front",
            "mockup_url": "https://url-to/front-mockup.png"
        },
        {
            "variant_ids": [
                4016,
                4017,
                4018
            ],
            "placement": "back",
            "mockup_url": "https://url-to/back-mockup.png"
        }
    ]
}

この時点では、モックアップURLをダウンロードして自分のサーバーに保存するだけでいいのです。

商品テンプレート

自分のデザイン作成ツールUIを構築したい場合、ここが開始場所です。 商品テンプレートエンドポイントを使用すると、ユーザーが自分のファイルを配置できるツールを作成するために必要なテンプレート画像と位置を取得することができます。

たとえば、マグツールを作成する場合、エンドポイント/mockup-generator/templates/19をマグ商品IDで呼び出します。 バリエーションマッピングフィールドを見ると、バリエーション132011オンスマグカップの場合、ID 919のテンプレートを使用する必要があることがわかります。      これがテンプレートの構造です。

{
    "template_id": 919,
    "image_url": "https://www.printful.com/files/generator/40/11oz_template.png",
    "background_url": null,
    "background_color": null,
    "printfile_id": 43,
    "template_width": 560,
    "template_height": 295,
    "print_area_width": 520,
    "print_area_height": 202,
    "print_area_top": 18,
    "print_area_left": 20,
    "is_template_on_front": true
}
  • printfile_id デザインデータエンドポイントから実際の印刷ファイルサイズを取得することができます。

  • template_width これはメインコンテナの幅、ピクセルです。

  • template_height メインコンテナーの高さ。

  • print_area_width 位置決めが行われる内側領域。

  • print_area_height 内部領域。

  • print_area_top メインコンテナーからのオフセット。

  • print_area_left メインコンテナーからのオフセット。

  • is_template_on_front これはユーザー画像をテンプレート画像の下に表示するか上に表示するかを示します。

この情報で簡単なHTMLマークアップを作成することができます。

<div style="position: relative; width: 520px; height: 295px;">
    <div style="position: absolute; width: 520px; height: 202px; top:18px; left:20px; background:rgba(255,233,230,0.33)">
        <img src="/static/images/layout/logo-printful.png" style="position: absolute; left: 43px; top: 77px; width: 140px; height: 63px;">
    </div>
    <div style="position: absolute; width: 560px; height: 295px; background:url(/files/generator/40/11oz_template.png) center center no-repeat"></div>
</div>

ブラウザでは次のようになります。

上記の位置でモックアップを生成するために、 POST リクエスト https://api.printful.com/mockup-generator/create-task/19 ボディパラメータを使って:

{
    "variant_ids" : [1320],
    "format": "jpg",
    "files" : [
        {
            "placement": "default",
            "image_url": "https://static.cdn.printful.com/static/v758/images/layout/logo-printful.png",
            "position": {
                "area_width": 520,
                "area_height": 202,
                "width": 140,
                "height": 63,
                "top": 77,
                "left": 43
            }
        }
    ]
}
  • area_width テンプレート内のprint_area_widthの値。

  • area_height テンプレート内のprint_area_heightの値。

  • width 画像の幅。

  • height 画像の高さ。

  • top 領域内の画像の上部オフセット。

  • left 領域内の左オフセット画像。

Endpoints

Create a mockup generation task

POST https://api.printful.com/mockup-generator/create-task/{id}

Creates an asynchronous mockup generation task. Generation result can be retrieved using mockup generation task retrieval endpoint.

Rate limiting: Up to 10 requests per 60 seconds. A 60 seconds lockout is applied if request count is exceeded.
Input parameters:
id integer Product ID.
Request body CreateGenerationTask Mockup generation data.
variant_ids integer [ ] List of variant ids you want to generate.
format {jpg, png} Generated file format. PNG will have a transparent background, JPG will have a smaller file size.
width integer Width of the resulting mockup images (min 50, max 1000, default is 1000)
product_options string [ ] Key-value list of product options (embroidery thread, stitch colors). Product options can be found in Catalog API endpoint.
option_groups string [ ] List of option group names you want to generate. Product's option groups can be found in printfile API request.
options string [ ] List of option names you want to generate. Product's options can be found in printfile API request.
files GenerationTaskFile [ ] Placement and file mapping to be generated.
placement string Placement identifier (front, back, etc.).
image_url string Public URL where your file is stored.
position GenerationTaskFilePosition Position
area_width integer Positioning area width on print area
area_height integer Positioning area height on print area
width integer Width of the image in given area
height integer Height of the image in given area
top integer Image top offset in given area
left integer Image left offset in given area
レスポンス形式:
code integer ステータスコードのレスポンス 200
result GenerationTask
task_key string Task identifier you will use to retrieve generated mockups.
status {pending, completed, failed} Status of the generation task.
error string If task has failed, reason will be provided here.
mockups GenerationTaskMockups [ ] If task is completed, list of mockups will be provided here.
placement string Placement identifier.
variant_ids integer [ ] List of variant ids this mockup is used for. One mockup can be used for multiple variants.
mockup_url string Temporary URL of the primary mockup.
extra GenerationTaskExtraMockup [ ] Optional extra mockups.
title string Display name of the extra mockup.
url string Temporary URL of the mockup.
option string Style option name
option_group string Style option group name
APIキー
id Product ID.
Request body
Execute

Retrieve product variant printfiles

GET https://api.printful.com/mockup-generator/printfiles/{id}

List of printfiles available for products variants. Printfile indicates what file resolution should be used to create a mockup or submit an order.
Input parameters:
id integer Product ID
orientation string Optional orientation for wall art product printfiles. Allowed values: horizontal, vertical
technique string Optional technique for product. This can be used in cases where product supports multiple techniques like DTG and embroidery
レスポンス形式:
code integer ステータスコードのレスポンス 200
result PrintfileInfo
product_id integer Requested product id.
available_placements object List of available placements. Key is placement identifier, value is display name. (e.g. {embroidery_front: Front, ..}).
printfiles Printfile [ ] Array of printfiles available for product.
printfile_id integer Unique printfile identifier.
width integer Width in pixels.
height integer Height in pixels.
dpi integer Resulting DPI for given width and height.
fill_mode {cover, fit} Indicates if printfile will be used in cover or fit mode. Cover mode can produce cropping if side ratio does not match printfile.
can_rotate boolean Indicates if printfile can be rotated horizontally (e.g. for posters).
variant_printfiles VariantPrintfile [ ] Each variant mapping to placement and their printfiles.
variant_id integer Product variant id.
placements object Key is placement and value is representing printfile_id. (e.g. {front: 1, back: 2, ..}).
option_groups string [ ] List of option groups available (e.g. for leggings Barefoot, High-heels, etc.). Note that not every variant has all groups available for generation.
options string [ ] List of options available for generation (e.g. Front, Back).
APIキー
id Product ID
orientation Optional orientation for wall art product printfiles. Allowed values: horizontal, vertical
technique Optional technique for product. This can be used in cases where product supports multiple techniques like DTG and embroidery
Execute

Mockup generation task result

GET https://api.printful.com/mockup-generator/task

Returns asynchronous mockup generation task result. If generation task is completed, it will contain a list of generated mockups.
Input parameters:
task_key string Task key retrieved when creating the generation task.
レスポンス形式:
code integer ステータスコードのレスポンス 200
result GenerationTask
task_key string Task identifier you will use to retrieve generated mockups.
status {pending, completed, failed} Status of the generation task.
error string If task has failed, reason will be provided here.
mockups GenerationTaskMockups [ ] If task is completed, list of mockups will be provided here.
placement string Placement identifier.
variant_ids integer [ ] List of variant ids this mockup is used for. One mockup can be used for multiple variants.
mockup_url string Temporary URL of the primary mockup.
extra GenerationTaskExtraMockup [ ] Optional extra mockups.
title string Display name of the extra mockup.
url string Temporary URL of the mockup.
option string Style option name
option_group string Style option group name
APIキー
task_key Task key retrieved when creating the generation task.
Execute

Layout templates

GET https://api.printful.com/mockup-generator/templates/{id}

Retrieve list of templates that can be used for client-side positioning.
Input parameters:
id int Product ID.
orientation string Optional orientation for wall art product templates. Allowed values: horizontal, vertical
technique string Optional technique for product. This can be used in cases where product supports multiple techniques like DTG and embroidery
レスポンス形式:
code integer ステータスコードのレスポンス 200
result ProductTemplates
version integer Resource version. If this changes, resources (positions, images, etc.) should be re-cached.
min_dpi integer Recommended minimum DPI for given product.
variant_mapping TemplateVariantMapping [ ] List of product variants mapped to templates. From this information you can determine which template should be used for a variant.
variant_id integer Product variant ID.
templates TemplateVariantMappingItem [ ] Product variant ID.
placement string Placement ID.
template_id integer Corresponding template id which should be used for this variant and placement combination.
templates Template [ ] List of templates. Use variant_mapping to determine which template corresponds to which product variant.
template_id integer Template ID.
image_url string Main template image URL.
background_url string Background image URL (optional).
background_color string HEX color code that should be used as a background color.
printfile_id integer Printfile ID that should be generated for this template. See printfile API endpoint for list of Printfiles.
template_width integer Width of the whole template in pixels.
template_height integer Height of the whole template in pixels.
print_area_width integer Print area width (image is positioned in this area).
print_area_height integer Print area height (image is positioned in this area).
print_area_top integer Print area top offset (offset in template).
print_area_left integer Print area left offset (offset in template).
is_template_on_front boolean Should the main template image (image_url) be used as an overlay or as a background.
orientation string Wall art product orientation. Possible values: horizontal, vertical, any
conflicting_placements TemplatePlacementConflict [ ] List of conflicting placements. Used to determine which placements can be used together.
placement string Placement ID
conflicts string [ ] List Placement IDs that are conflicting with given placement
APIキー
id Product ID.
orientation Optional orientation for wall art product templates. Allowed values: horizontal, vertical
technique Optional technique for product. This can be used in cases where product supports multiple techniques like DTG and embroidery
Execute

Printfulを試す準備はできましたか?