[go: up one dir, main page]
API Threads
Revenir à : Français (France)
Ce document a été mis à jour.
La traduction en Français (France) n’est pas encore terminée.
Anglais mis à jour : 3 oct.
Français (France) mis à jour : 12 août

Threads Posts

You can use the Threads API to publish image, video, text, or carousel posts.

This document covers:

Single Thread Posts

Publishing a single image, video, or text post is a two-step process:

  1. Create a media container with text only or with an image or video hosted on your public server with optional text using the POST /{threads-user-id}/threads endpoint.
  2. Publish the media container using the POST /{threads-user-id}/threads_publish endpoint.

Limitations

  • Text posts are limited to 500 characters.

Step 1: Create a Threads media container

Use the POST /{threads-user-id}/threads endpoint to create a Threads media container.

Parameters

NameDescription

is_carousel_item

Boolean

Required.
Indicates that images and/or videos will appear in a carousel.

Values: true, false (default for single thread posts)

media_type

string

Required.
Indicates the current media type.

Values: TEXT, IMAGE, VIDEO

Note: CAROUSEL is not available for single thread posts.

image_url

URL

Optional. Required for media_type=IMAGE.
The URL path to the image.

Note: We will cURL your image using the URL provided so it must be on a public server.

video_url

URL

Optional. Required for media_type=VIDEO.
The URL path to the video.

Note: We will cURL your video using the URL provided so it must be on a public server.

text

string

Optional. Required for media_type=TEXT.
The text associated with the post. If any URLs are included, the first URL in the text field will be used as the link preview for the post.

Refer to the POST /{threads-user-id}/threads endpoint reference for additional supported parameters.

Example Request

curl -i -X POST \
  -d "media_type=IMAGE" \
  -d "image_url=<IMAGE_URL>" \
  -d "text=<TEXT>" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Example Response

{
  "id": "<THREADS_MEDIA_CONTAINER_ID>"
}

Step 2: Publish the Threads media container

Use the POST /{threads-user-id}/threads_publish endpoint to publish the media container ID returned in the previous step.

It is recommended to wait on average 30 seconds before publishing a Threads media container to give our server enough time to fully process the upload. See the media container status endpoint for more details.

Parameters

NameDescription

creation_id

int

Required.
The Threads media container ID.

Example Request

curl -i -X POST \
  -d "creation_id=<MEDIA_CONTAINER_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publish"

Example Response

{
  "id": "<THREADS_MEDIA_ID>"
}

Carousel Posts

You may publish up to 20 images, videos, or a mix of the two in a carousel post. Publishing carousels is a three-step process:

  1. Create the individual media containers for each image and video that should appear in the carousel using the POST /{threads-user-id}/threads endpoint.
  2. Create a single carousel container to contain the media containers using the POST /{threads-user-id}/threads endpoint.
  3. Publish the carousel container using the POST /{threads-user-id}/threads_publish endpoint.

Carousel posts count as a single post against a profile's rate limit.

Limitations

  • Carousels are limited to 20 images, videos, or a mix of the two.
  • Carousels require a minimum of two children.

Step 1: Create an media container

Use the POST /{threads-user-id}/threads endpoint to create a media container for each of the images and/or videos that will appear in the carousel.

Parameters

NameDescription

is_carousel_item

Boolean

Required.
Indicates that images and/or videos will appear in a carousel when set to true.

Values: true, false

media_type

string

Required.
Indicates the current media type.

Values: IMAGE, VIDEO

Note: CAROUSEL is not available for single thread posts.

image_url

URL

Optional. Required for media_type=IMAGE.
The URL path to the image.

Note: We will cURL your image using the URL provided so it must be on a public server.

video_url

URL

Optional. Required for media_type=VIDEO.
The URL path to the video.

Note: We will cURL your video using the URL provided so it must be on a public server.

text

string

Optional.
The text associated with the post. If any URLs are included, the first URL in the text field will be used as the link preview for the post.

Refer to the POST /{threads-user-id}/threads endpoint reference for additional supported parameters.

Example Request

curl -i -X POST \
  -d "image_url=<IMAGE_URL>" \
  -d "is_carousel_item=true" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Example Response

{
  "id": "<THREADS_MEDIA_CONTAINER_ID>"
}

If the operation is successful, the API will return an media container ID, which can be used when creating the carousel container.

Repeat this process for each image and/or video that will appear in the carousel.

Step 2: Create a carousel container

Use the POST /{threads-user-id}/threads endpoint to create a carousel container.

Parameters

NameDescription

media_type

string

Required.
Indicates the current media type.

Value: CAROUSEL

children

list<int>

Required.
A comma-separated list of the media container IDs of the images and/or videos that should appear in the published carousel.

Note: Carousels must have at least 2 and no more than 20 total images, videos, or a mix of the two.

text

string

Optional.
The text associated with the post.

Refer to the POST /{threads-user-id}/threads endpoint reference for additional supported parameters.

Example Request

curl -i -X POST \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>,..." \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Example Response

{
  "id": "<THREADS_CAROUSEL_CONTAINER_ID>"
}

Step 3: Publish the carousel container

Use the POST /{threads-user-id}/threads_publish endpoint to publish a carousel post.

Note: Profiles are limited to 250 published posts within a 24-hour period. Publishing a carousel counts as a single post.

Parameters

NameDescription

creation_id

int

Required.
The Threads carousel container ID.

Example Request

curl -i -X POST \
  -d "creation_id=<MEDIA_CONTAINER_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publish"

Example Response

{
  "id": "<THREADS_MEDIA_ID>"
}

If the operation is successful, the API will return the carousel album's Threads media ID.

Topic Tags and Links in Posts

Topics and links appear in posts in such a way as to encourage engagement.

Topic Tags

Topics make posts more social by allowing central topics of discussion. You can include a topic in a post either by using the topic_tag parameter or by including a tag within the text of a post.

Using the topic_tag parameter

Note: Topic tags must be at least 1 character and no more than 50 characters long. The following characters are not allowed:

  • Periods (.)
  • Ampersands (&)
curl -i -X POST \
  -d "media_type=TEXT" \
  -d "text=<Text>" \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "topic_tag=<TAG>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Using an in-text topic tag

This method is not preferred but is kept for backwards compatability.

A topic can also be attached to a post by including it in-line within the text of the post. Only one topic tag is allowed per post, so the first valid tag included in a post of any type (text-only, image, video, carousel) via the API is treated as the tag for that post.

Information to keep in mind when adding a topic to a post using an in-text tag:

  • Valid tags start with a hash sign (#).
  • The text is also configured in the app without the hash sign.
  • Topic must be at least 1 character and no more than 50 characters long.
  • Whole numbers that are preceded by a hash sign (i.e., #1) will not be converted into a tag. This is because it is assumed that # is signifying a number sign in this scenario.

  • The following characters are not allowed when using in-text tags with the Threads API, so any in-text tag that starts with a hash sign will end just before these characters:

    • Spaces, Tabs, New Line Characters
    • Periods (.)
    • Ampersands (&)
    • At Signs (@)
    • Exclamation Marks (!)
    • Question Marks (?)
    • Commas (,)
    • Semi-Colons (;)
    • Colons (:)

Links

To attach a link to your post, use the link_attachment parameter when creating a media container. If no link_attachment parameter is provided, then the first link made in a text-only post via the API is configured as the link attachment, which displays as a preview card, to make it easier to engage with and click on.

Limitations

  • This feature is only available for text-only posts. It will not work with image, video, and carousel posts.

Publishing

Links can be attached when making an API call to the POST /threads endpoint to create a media container.

NameDescription

link_attachment

URL

Optional.
The URL that should be attached to a Threads post and displayed as a link preview. This must be a valid, publicly accessible URL.

Note: Can only be used for media_type=TEXT posts.

Example Request
curl -i -X POST \  
  -d "media_type=TEXT" \
  -d "text=<TEXT>" \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "link_attachment=<URL> \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"
Example Response
{
  "id": "<THREADS_MEDIA_CONTAINER_ID>"
}

The request above creates a Threads media container that, once published, will attach a link preview to your media.

Media Retrieval

The value for the link_attachment URL can be retrieved by making a request to the GET /threads or GET /{threads_media_id} endpoint to retrieve media object(s).

NameDescription

link_attachment_url

URL

The URL attached to a Threads post.

Example Request
curl -s -X GET \ 
"https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,link_attachment_url&access_token=<ACCESS_TOKEN>"
Example Response
{
   "id": "<THREADS_MEDIA_ID>",
   "link_attachment_url": "<LINK_ATTACHMENT_URL>",
}

Media Specifications

Caractéristiques des images

  • Format : les images JPEG et PNG sont les formats officiellement pris en charge pour les publications de type image.
  • Taille de fichier : 8 Mo maximum.
  • Limite de proportions : 10:1
  • Largeur minimale : 320 (sera mise à l’échelle au minimum si nécessaire)
  • Largeur maximale : 1 440 (sera mise à l’échelle au maximum si nécessaire)
  • Hauteur : variable (selon la largeur et les proportions)
  • Espace colorimétrique : sRGB. Les images utilisant d’autres espaces colorimétriques verront ces espaces convertis en sRGB.

Caractéristiques vidéo

  • Conteneur : MOV ou MP4 (MPEG-4 Part 14), sans listes de modification, métadonnées moov atom au début du fichier.
  • Codec audio : AAC, fréquence d’échantillonnage maximum 48 kHz, 1 ou 2 canaux (mono ou stéréo).
  • Codec vidéo : HEVC ou H264, balayage progressif, GOP fermé, sous-échantillonnage chromatique 4:2:0.
  • Fréquence d’images : 23-60 images par seconde
  • Taille d’image :
    • Colonnes maximales (pixels horizontaux) : 1 920
    • Les proportions doivent être comprises entre 0,01:1 et 10:1, mais nous recommandons 9:16 pour éviter les espaces vides ou à rogner.
  • Débit vidéo : VBR, 100 Mbit/s maximum.
  • Débit audio : 128 kbit/s.
  • Durée : 300 secondes (5 minutes) maximum, plus de 0 seconde.
  • Taille de fichier : 1 Go maximum.

Learn More