encrypt_stream / decrypt_stream), /2/chat/media/upload 경로(사이드바 API 레퍼런스 → Media)로 업로드한 다음, encrypt_message에 **media_hash_key**를 첨부하세요.
업로드 시 DM 스코프에 **media.write**를 포함하세요. 경로에는 하이픈이 있는 대화 ID를 사용하세요(: → -). MIME/치수는 복호화된 바이트에서 얻는 것을 권장합니다.
이 경로는 Posts 미디어 모델(expansions=attachments.media_keys, media.fields=variants 등)이 아닙니다. 이러한 매개변수는 Posts에 적용됩니다; E2EE X Chat blob은 **media_hash_key**와 X Chat 미디어 다운로드로 주소가 지정됩니다.
암호화
- Python
- TypeScript
- Rust
- Go
- C#
- Java
encrypt_stream / decrypt_stream은 전체 페이로드를 메모리에서 처리합니다. 대용량 파일의 경우 stream_encryptor() / stream_decryptor()는 증분 객체(StreamEncryptor / StreamDecryptor)를 반환합니다: push로 청크를 공급한 다음 finish를 한 번 호출하세요—스트림이 잘렸다면 finish가 오류를 발생시킵니다.
업로드
API 레퍼런스 → Media 아래의 OpenAPI 페이지에서 요청 본문을 사용하세요. 크기가 필요한 경우 암호화된 blob 크기를 선호하세요. Finalize는 첨부 및 다운로드에 사용할 **
media_hash_key**를 반환합니다. 일시적인 5xx는 백오프로 재시도하세요. Python/TypeScript는 미디어 헬퍼가 존재할 때 XDK를 사용할 수 있고, 그렇지 않으면 어떤 언어에서든 Bearer 토큰으로 POST하세요.
첨부 파일과 함께 전송
미디어 첨부와 함께 암호화한 다음 send-message 본문을 POST하세요(시작하기와 동일한 필드 매핑). SDK가message_id를 생성하여 페이로드에 반환합니다—그 값을 전송하고 재시도 시에도 동일한 페이로드를 재사용하여 ID가 두 번 생성되지 않도록 하세요.
- Python
- TypeScript
- Rust
- Go
- C#
- Java
set_cache_keys(true)이 활성화되면 encrypt_message가 대화의 최신 검증된 키 변경에서 키와 버전을 해석합니다(시작하기 참고).
다운로드 및 복호화
경로:GET /2/chat/media/{conversation_id}/{media_hash_key}. 응답 본문은 암호문입니다. 수신 메시지에서는 복호화된 첨부 파일 / media_hashes에서 media_hash_key를 읽으세요.
이벤트의 키 버전으로 키를 선택하세요. 각 복호화된 메시지 이벤트는 콘텐츠가 암호화된 keyVersion(JS의 경우; 다른 바인딩은 key_version)을 가집니다. 첨부 파일은 해당 버전의 대화 키로 복호화하세요—conversationKeys.keys[event.keyVersion]—최신 버전이 아닙니다. 키 순환(예: 멤버 추가) 후에는 최신 키가 이전 메시지에 첨부된 미디어를 복호화할 수 없습니다.
- Python
- TypeScript
- Python
- TypeScript
- Rust
- Go
- C#
- Java
팁
- 미디어가 암호화될 때와 동일한 대화 키 버전을 사용하세요
- 평문 미디어나 원시 키를 로깅하지 마세요
- MIME은 복호화 후에 감지하세요
- 웹 클라이언트: 가능한 경우 클라이언트에서 암호화/복호화하고 OAuth 토큰은 서버에 유지하세요