Create a media container

POST

meta

v25.0

{instagramAccountId}

media

Create a media container

curl --request POST \
  --url https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media \
  --header 'Content-Type: application/json' \
  --data '
{
  "image_url": "<string>",
  "video_url": "<string>",
  "media_type": "<string>",
  "caption": "<string>",
  "is_carousel_item": true,
  "children": "<string>",
  "cover_url": "<string>",
  "alt_text": "<string>",
  "user_tags": [
    {}
  ],
  "collaborators": [
    {}
  ],
  "location_id": "<string>",
  "thumb_offset": 123,
  "audio_name": "<string>",
  "trial_params": {}
}
'

import requests

url = "https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media"

payload = {
    "image_url": "<string>",
    "video_url": "<string>",
    "media_type": "<string>",
    "caption": "<string>",
    "is_carousel_item": True,
    "children": "<string>",
    "cover_url": "<string>",
    "alt_text": "<string>",
    "user_tags": [{}],
    "collaborators": [{}],
    "location_id": "<string>",
    "thumb_offset": 123,
    "audio_name": "<string>",
    "trial_params": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    image_url: '<string>',
    video_url: '<string>',
    media_type: '<string>',
    caption: '<string>',
    is_carousel_item: true,
    children: '<string>',
    cover_url: '<string>',
    alt_text: '<string>',
    user_tags: [{}],
    collaborators: [{}],
    location_id: '<string>',
    thumb_offset: 123,
    audio_name: '<string>',
    trial_params: {}
  })
};

fetch('https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'image_url' => '<string>',
    'video_url' => '<string>',
    'media_type' => '<string>',
    'caption' => '<string>',
    'is_carousel_item' => true,
    'children' => '<string>',
    'cover_url' => '<string>',
    'alt_text' => '<string>',
    'user_tags' => [
        [
                
        ]
    ],
    'collaborators' => [
        [
                
        ]
    ],
    'location_id' => '<string>',
    'thumb_offset' => 123,
    'audio_name' => '<string>',
    'trial_params' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media"

	payload := strings.NewReader("{\n  \"image_url\": \"<string>\",\n  \"video_url\": \"<string>\",\n  \"media_type\": \"<string>\",\n  \"caption\": \"<string>\",\n  \"is_carousel_item\": true,\n  \"children\": \"<string>\",\n  \"cover_url\": \"<string>\",\n  \"alt_text\": \"<string>\",\n  \"user_tags\": [\n    {}\n  ],\n  \"collaborators\": [\n    {}\n  ],\n  \"location_id\": \"<string>\",\n  \"thumb_offset\": 123,\n  \"audio_name\": \"<string>\",\n  \"trial_params\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media")
  .header("Content-Type", "application/json")
  .body("{\n  \"image_url\": \"<string>\",\n  \"video_url\": \"<string>\",\n  \"media_type\": \"<string>\",\n  \"caption\": \"<string>\",\n  \"is_carousel_item\": true,\n  \"children\": \"<string>\",\n  \"cover_url\": \"<string>\",\n  \"alt_text\": \"<string>\",\n  \"user_tags\": [\n    {}\n  ],\n  \"collaborators\": [\n    {}\n  ],\n  \"location_id\": \"<string>\",\n  \"thumb_offset\": 123,\n  \"audio_name\": \"<string>\",\n  \"trial_params\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image_url\": \"<string>\",\n  \"video_url\": \"<string>\",\n  \"media_type\": \"<string>\",\n  \"caption\": \"<string>\",\n  \"is_carousel_item\": true,\n  \"children\": \"<string>\",\n  \"cover_url\": \"<string>\",\n  \"alt_text\": \"<string>\",\n  \"user_tags\": [\n    {}\n  ],\n  \"collaborators\": [\n    {}\n  ],\n  \"location_id\": \"<string>\",\n  \"thumb_offset\": 123,\n  \"audio_name\": \"<string>\",\n  \"trial_params\": {}\n}"

response = http.request(request)
puts response.read_body

Step 1 of the publish flow. Creates a media container from a public HTTPS media URL.
Poll the returned container ID until status_code is FINISHED, then publish it.

Authentication

Use the hmat_ channel token from GET /meta/channels/{id}/token or hookmyapp channels env <channel>. Do not use an hmok_ API key for this call.

Authorization: Bearer hmat_...

Path parameters

string

required

The connected Instagram account ID.

Request body

string

Public HTTPS URL of a JPEG image. Required for images; either this or video_url for stories.

string

Public HTTPS URL of a video. Required for reels; either this or image_url for stories.

string

REELS, STORIES, or CAROUSEL. Omit for a feed image.

string

Post caption.

boolean

Set true when creating a child container for a carousel. Child containers take image_url (or video_url with media_type=VIDEO) and no caption.

string

For the carousel parent (media_type=CAROUSEL): the child container IDs created with is_carousel_item=true, as a comma-separated string (for example "17890000000000001,17890000000000002"). 2–10 items.

string

Cover image URL for reels.

string

Alt text for an image post, up to 1000 characters. Single images and carousel image children only.

array

Tag public accounts: [{"username":"someuser","x":0.5,"y":0.8}]. x/y position the tag on images. Images, videos, stories, and carousel children.

array

Invite accounts to collaborate: ["username1","username2"]. Each gets an invite, and once they accept, the post also shows on their profile. Images, reels, and the carousel parent (not carousel children).

string

Facebook Page ID of a place to tag. The Page must have location data. Feed posts and reels.

number

Cover frame for videos and reels, in milliseconds from the start. Ignored when cover_url is set.

string

Name of the reel’s audio. Can only be set once.

object

Reels only: publish as a trial reel. {"graduation_strategy":"MANUAL"} or "SS_PERFORMANCE".

See media requirements for size, format, and quota limits.

Example

curl -X POST "https://gateway.hookmyapp.com/meta/v25.0/{INSTAGRAM_ACCOUNT_ID}/media" \
  -H "Authorization: Bearer hmat_..." \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/photo.jpg", "caption": "New drop" }'

Successful response

{ "id": "17900000000000001" }

Containers expire after 24 hours.

Create a media container

curl --request POST \
  --url https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media \
  --header 'Content-Type: application/json' \
  --data '
{
  "image_url": "<string>",
  "video_url": "<string>",
  "media_type": "<string>",
  "caption": "<string>",
  "is_carousel_item": true,
  "children": "<string>",
  "cover_url": "<string>",
  "alt_text": "<string>",
  "user_tags": [
    {}
  ],
  "collaborators": [
    {}
  ],
  "location_id": "<string>",
  "thumb_offset": 123,
  "audio_name": "<string>",
  "trial_params": {}
}
'

import requests

url = "https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media"

payload = {
    "image_url": "<string>",
    "video_url": "<string>",
    "media_type": "<string>",
    "caption": "<string>",
    "is_carousel_item": True,
    "children": "<string>",
    "cover_url": "<string>",
    "alt_text": "<string>",
    "user_tags": [{}],
    "collaborators": [{}],
    "location_id": "<string>",
    "thumb_offset": 123,
    "audio_name": "<string>",
    "trial_params": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    image_url: '<string>',
    video_url: '<string>',
    media_type: '<string>',
    caption: '<string>',
    is_carousel_item: true,
    children: '<string>',
    cover_url: '<string>',
    alt_text: '<string>',
    user_tags: [{}],
    collaborators: [{}],
    location_id: '<string>',
    thumb_offset: 123,
    audio_name: '<string>',
    trial_params: {}
  })
};

fetch('https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'image_url' => '<string>',
    'video_url' => '<string>',
    'media_type' => '<string>',
    'caption' => '<string>',
    'is_carousel_item' => true,
    'children' => '<string>',
    'cover_url' => '<string>',
    'alt_text' => '<string>',
    'user_tags' => [
        [
                
        ]
    ],
    'collaborators' => [
        [
                
        ]
    ],
    'location_id' => '<string>',
    'thumb_offset' => 123,
    'audio_name' => '<string>',
    'trial_params' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media"

	payload := strings.NewReader("{\n  \"image_url\": \"<string>\",\n  \"video_url\": \"<string>\",\n  \"media_type\": \"<string>\",\n  \"caption\": \"<string>\",\n  \"is_carousel_item\": true,\n  \"children\": \"<string>\",\n  \"cover_url\": \"<string>\",\n  \"alt_text\": \"<string>\",\n  \"user_tags\": [\n    {}\n  ],\n  \"collaborators\": [\n    {}\n  ],\n  \"location_id\": \"<string>\",\n  \"thumb_offset\": 123,\n  \"audio_name\": \"<string>\",\n  \"trial_params\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media")
  .header("Content-Type", "application/json")
  .body("{\n  \"image_url\": \"<string>\",\n  \"video_url\": \"<string>\",\n  \"media_type\": \"<string>\",\n  \"caption\": \"<string>\",\n  \"is_carousel_item\": true,\n  \"children\": \"<string>\",\n  \"cover_url\": \"<string>\",\n  \"alt_text\": \"<string>\",\n  \"user_tags\": [\n    {}\n  ],\n  \"collaborators\": [\n    {}\n  ],\n  \"location_id\": \"<string>\",\n  \"thumb_offset\": 123,\n  \"audio_name\": \"<string>\",\n  \"trial_params\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://gateway.hookmyapp.com/meta/v25.0/{instagramAccountId}/media")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"image_url\": \"<string>\",\n  \"video_url\": \"<string>\",\n  \"media_type\": \"<string>\",\n  \"caption\": \"<string>\",\n  \"is_carousel_item\": true,\n  \"children\": \"<string>\",\n  \"cover_url\": \"<string>\",\n  \"alt_text\": \"<string>\",\n  \"user_tags\": [\n    {}\n  ],\n  \"collaborators\": [\n    {}\n  ],\n  \"location_id\": \"<string>\",\n  \"thumb_offset\": 123,\n  \"audio_name\": \"<string>\",\n  \"trial_params\": {}\n}"

response = http.request(request)
puts response.read_body

Getting started

Sending & receiving

Publish & engage

Tools

API Reference

Create a media container

Authentication

Path parameters

Request body

Example

Successful response

​Authentication

​Path parameters

​Request body

​Example

​Successful response

Authentication

Path parameters

Request body

Example

Successful response