Multimedia y adjuntos

Las imágenes y otros archivos usan la misma clave de conversación que el texto. Cifra los bytes con el Chat XDK (encrypt_stream / decrypt_stream), sube mediante las rutas /2/chat/media/upload (barra lateral API reference → Media) y luego adjunta media_hash_key en encrypt_message. Incluye media.write con tus scopes de DM al subir. Usa ids de conversación con guión en las rutas (: → -). Prefiere el MIME/dimensiones desde los bytes descifrados. Este camino no es el modelo de multimedia de Posts (expansions=attachments.media_keys, media.fields=variants, etc.). Esos parámetros aplican a Posts; los blobs E2EE de X Chat se direccionan por media_hash_key y por la descarga de multimedia de X Chat.

Cifrar

from chat_xdk import detect_mime_type, detect_image_dimensions

with open("photo.jpg", "rb") as f:
    plaintext = f.read()

mime = detect_mime_type(plaintext)
dims = detect_image_dimensions(plaintext)
width, height = dims if dims else (0, 0)

encrypted_blob = chat.encrypt_stream(plaintext, raw_conv_key)

import { detectMimeType, detectImageDimensions } from '@xdevplatform/chat-xdk';
import { readFile } from 'fs/promises';

const plaintext = await readFile('photo.jpg');
const mime = detectMimeType(plaintext);
const dims = detectImageDimensions(plaintext);
const width = dims?.width ?? 0;
const height = dims?.height ?? 0;

const encryptedBlob = chat.encryptStream(plaintext, rawConvKey);

use chat_xdk_core::{detect_image_dimensions, detect_mime_type};

let plaintext = std::fs::read("photo.jpg")?;
let _mime = detect_mime_type(&plaintext);
let dims = detect_image_dimensions(&plaintext);
let (width, height) = dims.map(|d| (d.width as i64, d.height as i64)).unwrap_or((0, 0));
// conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
let encrypted_blob = chat.encrypt_stream(&plaintext, &conv_key)?;

plaintext, err := os.ReadFile("photo.jpg")
mime, _ := chatxdk.DetectMimeType(plaintext)
dims, _ := chatxdk.DetectImageDimensions(plaintext)
_ = mime
encrypted, err := chat.EncryptStream(plaintext, rawConvKey)
_ = dims
_ = encrypted

using ChatXdk;

byte[] plaintext = await File.ReadAllBytesAsync("photo.jpg");
string? mime = ChatXdkUtilities.DetectMimeType(plaintext);
var dims = ChatXdkUtilities.DetectImageDimensions(plaintext);
int width = (int)(dims?.Width ?? 0);
int height = (int)(dims?.Height ?? 0);
byte[] encryptedBlob = chat.EncryptStream(plaintext, rawConvKey);

import com.x.chatxdk.ChatXdkUtilities;
import com.x.chatxdk.Types.ImageDimensions;

byte[] plaintext = Files.readAllBytes(Path.of("photo.jpg"));
String mime = ChatXdkUtilities.detectMimeType(plaintext);
ImageDimensions dims = ChatXdkUtilities.detectImageDimensions(plaintext);
int width = dims != null ? (int) dims.width : 0;
int height = dims != null ? (int) dims.height : 0;
byte[] encryptedBlob = chat.encryptStream(plaintext, rawConvKey);

encrypt_stream / decrypt_stream procesan la carga completa en memoria. Para archivos grandes, stream_encryptor() / stream_decryptor() devuelven objetos incrementales (StreamEncryptor / StreamDecryptor): aliméntalos por fragmentos con push y luego llama a finish una vez—finish arroja error si el stream se truncó.

Subir

Paso	Método	Ruta
Inicializar	`POST`	`/2/chat/media/upload/initialize`
Añadir	`POST`	`/2/chat/media/upload/{id}/append`
Finalizar	`POST`	`/2/chat/media/upload/{id}/finalize`

Usa los cuerpos de solicitud en las páginas de OpenAPI bajo API reference → Media. Prefiere el tamaño del blob cifrado donde se requiera el tamaño. Finalizar produce media_hash_key para adjuntos y descarga. Reintenta 5xx transitorios con backoff. Python/TypeScript pueden usar el XDK cuando existan helpers de multimedia; en caso contrario, haz POST con un Bearer token en cualquier lenguaje.

Enviar con un adjunto

Cifra con un adjunto de multimedia y luego haz POST del cuerpo send-message (mismo mapeo de campos que en Primeros pasos).

import uuid
from xdk.chat.models import SendMessageRequest

message_id = str(uuid.uuid4())
payload = chat.encrypt_message(
    message_id,
    sender_id,
    conversation_id,
    raw_conv_key,
    caption or "",
    conversation_key_version,
    signing_key_version,
    attachments=[{
        "attachment_type": "media",
        "media_hash_key": media_hash_key,
        "width": width,
        "height": height,
        "filesize_bytes": len(plaintext),
        "filename": "photo.jpg",
    }],
)
client.chat.send_message(
    conversation_id.replace(":", "-"),
    SendMessageRequest(
        message_id=message_id,
        encoded_message_create_event=payload.encrypted_content,
        encoded_message_event_signature=payload.encoded_event_signature,
    ),
)

const messageId = crypto.randomUUID();
const payload = chat.encryptMessage({
  messageId,
  senderId,
  conversationId,
  conversationKey: rawConvKey,
  text: caption || '',
  conversationKeyVersion,
  signingKeyVersion,
  attachments: [{
    attachmentType: 'media',
    mediaHashKey: mediaHashKey,
    width,
    height,
    filesizeBytes: plaintext.byteLength,
    filename: 'photo.jpg',
  }],
});
await client.chat.sendMessage(conversationId.replace(/:/g, '-'), {
  message_id: messageId,
  encoded_message_create_event: payload.encryptedContent,
  encoded_message_event_signature: payload.encodedEventSignature,
});

// Set attachments on EncryptMessageParams per chat_xdk_core AttachmentDescriptor::Media
let payload = chat.encrypt_message(params_with_media_attachment)?;
let body = serde_json::json!({
    "message_id": message_id,
    "encoded_message_create_event": payload.encrypted_content,
    "encoded_message_event_signature": payload.encoded_event_signature,
});
let path_id = conversation_id.replace(':', "-");
http.post(format!("https://api.x.com/2/chat/conversations/{path_id}/messages"))
    .header("Authorization", &auth)
    .json(&body)
    .send()?;

payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
    MessageID: messageID, SenderID: senderID, ConversationID: conversationID,
    ConversationKey: rawConvKey, Text: caption,
    ConversationKeyVersion: conversationKeyVersion, SigningKeyVersion: signingKeyVersion,
    Attachments: []chatxdk.AttachmentDescriptor{{
        AttachmentType: "media",
        MediaHashKey:   mediaHashKey,
        Width:          width,
        Height:         height,
        FilesizeBytes:  int64(len(plaintext)),
        Filename:       "photo.jpg",
    }},
})
// POST payload.EncryptedContent / EncodedEventSignature to /2/chat/conversations/{id}/messages

var payload = chat.EncryptMessage(new EncryptMessageParams {
    MessageId = messageId,
    SenderId = senderId,
    ConversationId = conversationId,
    ConversationKey = rawConvKey,
    Text = caption ?? "",
    ConversationKeyVersion = conversationKeyVersion,
    SigningKeyVersion = signingKeyVersion,
    // Attachments = media descriptor with MediaHashKey, Width, Height,
    // FilesizeBytes, and Filename (as in the Go tab above)
});
// POST EncryptedContent / EncodedEventSignature as for text messages

EncryptMessageParams params = new EncryptMessageParams();
params.messageId = messageId;
params.senderId = senderId;
params.conversationId = conversationId;
params.conversationKey = rawConvKey;
params.text = caption != null ? caption : "";
params.conversationKeyVersion = conversationKeyVersion;
params.signingKeyVersion = signingKeyVersion;
// params.attachments — media type with mediaHashKey, width, height, filename
SendPayload payload = chat.encryptMessage(params);
// POST to /2/chat/conversations/{id}/messages

Descargar y descifrar

Ruta: GET /2/chat/media/{conversation_id}/{media_hash_key}. El cuerpo de la respuesta es texto cifrado. En los mensajes entrantes, lee media_hash_key desde los adjuntos descifrados / media_hashes. Elige la clave por la versión de clave del evento. Cada evento de mensaje descifrado lleva la keyVersion (JS; key_version en los demás bindings) con la que se cifró su contenido. Descifra un adjunto con la clave de conversación de esa versión—conversationKeys.keys[event.keyVersion]—no la más reciente. Después de una rotación de clave (por ejemplo al agregar un miembro), la clave más reciente no puede descifrar multimedia adjunta a mensajes anteriores.

Python
TypeScript

keys = result["conversation_keys"]["keys"]
key_for_media = keys[event["key_version"]]   # not the latest version
plaintext = chat.decrypt_stream(encrypted_blob, key_for_media)

const keys = result.conversationKeys.keys;
const keyForMedia = keys[event.keyVersion]; // not the latest version
const plaintext = chat.decryptStream(encryptedBlob, keyForMedia);

import requests
from chat_xdk import detect_mime_type

api_id = conversation_id.replace(":", "-")
url = f"https://api.x.com/2/chat/media/{api_id}/{media_hash_key}"
r = requests.get(url, headers={"Authorization": f"Bearer {access_token}"})
r.raise_for_status()

plaintext = chat.decrypt_stream(r.content, raw_conv_key)
mime = detect_mime_type(plaintext) or "application/octet-stream"

import { detectMimeType } from '@xdevplatform/chat-xdk';

const apiId = conversationId.replace(/:/g, '-');
const res = await fetch(
  `https://api.x.com/2/chat/media/${apiId}/${mediaHashKey}`,
  { headers: { Authorization: `Bearer ${accessToken}` } },
);
const encryptedBlob = new Uint8Array(await res.arrayBuffer());
const plaintext = chat.decryptStream(encryptedBlob, rawConvKey);
const mime = detectMimeType(plaintext) ?? 'application/octet-stream';

let api_id = conversation_id.replace(':', "-");
let encrypted_blob = http
    .get(format!("https://api.x.com/2/chat/media/{api_id}/{media_hash_key}"))
    .header("Authorization", &auth)
    .send()?
    .bytes()?;
// conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
let plaintext = chat.decrypt_stream(&encrypted_blob, &conv_key)?;

url := fmt.Sprintf("https://api.x.com/2/chat/media/%s/%s",
    strings.ReplaceAll(conversationID, ":", "-"), mediaHashKey)
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Authorization", "Bearer "+accessToken)
resp, err := http.DefaultClient.Do(req)
// read body into []byte → chat.DecryptStream(encryptedBlob, rawConvKey)
_ = resp
_ = err

var apiId = conversationId.Replace(':', '-');
byte[] encryptedBlob = await http.GetByteArrayAsync(
    $"https://api.x.com/2/chat/media/{apiId}/{mediaHashKey}");
byte[] plaintext = chat.DecryptStream(encryptedBlob, rawConvKey);
string? mime = ChatXdkUtilities.DetectMimeType(plaintext);

String apiId = conversationId.replace(':', '-');
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.x.com/2/chat/media/" + apiId + "/" + mediaHashKey))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();
byte[] encryptedBlob = http.send(req, HttpResponse.BodyHandlers.ofByteArray()).body();
byte[] plaintext = chat.decryptStream(encryptedBlob, rawConvKey);
String mime = ChatXdkUtilities.detectMimeType(plaintext);

Consejos

Usa la misma versión de clave de conversación que cuando se cifró la multimedia
No registres multimedia en texto plano ni claves en bruto
Detecta el MIME después de descifrar
Clientes web: cifra/descifra en el cliente cuando sea posible; mantén los tokens de OAuth en tu servidor

Los esquemas completos de solicitud y respuesta para cada ruta de multimedia están bajo API reference → Media en la barra lateral (inicializar subida, añadir chunk, finalizar subida y descargar multimedia).

​Cifrar

​Subir

​Enviar con un adjunto

​Descargar y descifrar

​Consejos

Cifrar

Subir

Enviar con un adjunto

Descargar y descifrar

Consejos